REST API
Your mailbox, over plain HTTP.
Send, read and manage mail from your own code. Each key holds only the scopes you grant it.
In short
What is an email API?
An email API lets software send and read mail over HTTP, not through an app. A key on each request decides what the caller may touch.
104
documented operations
25
whole domains in one key's send scope
50
single addresses on top of those
How it works
Scope each key to one job
Pick the scopes a key holds, and optionally the senders it may use. A missing scope or an unlisted sender gets a 403.
Retry without sending it twice
Each send gets its msg_ id before anything goes out. A retry with the same Idempotency-Key returns the first result.
Rotate the secret, keep the key
Rotating swaps only the secret, so the id, scopes and request history carry on. A revoked key is told revoked_api_key.
Scopes a key can carry
Thirty in all. New keys start with emails:send.
Send your first email
Plain HTTP and JSON. Nothing to install.
curl -X POST https://api.openemail.uk/emails \ -H "Authorization: Bearer $OPENEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "Acme Billing <[email protected]>", "to": ["[email protected]"], "subject": "Your September invoice", "html": "<p>Invoice attached.</p>" }'What you get
In the product today
Every send has an id
/events per recipient, /tracking for opens and clicks.
A 403 explained
GET /ping shows the key's scopes and what its role left.
Keys over MCP
The MCP server lists, rotates, revokes and enables keys too.
Good practice
Getting the most out of it
- 01
One key per service
Revoking a leaked key then stops one integration, not all of them.
- 02
Set an Idempotency-Key
Derive it from something unique, like an invoice number, so a retry replays.
- 03
Narrow the sender
List only the addresses a service sends from. A whole domain covers ones added later.
Where it stands
Good to know
- No upload endpoint
- Inline attachments are base64, 5 MB in total. Larger files go by workspace file id, as a download link.
- No bounced state on a send
- GET /emails lists a bounced message as sent. The bounce shows on its recipient and in an email.bounced webhook.
Questions
Asked often
Keep going
Works well with
Start
Your domain,
your mail.
Point a domain at OpenEmail and read it in a mailbox built around it. The free plan covers one domain.
