---
title: "REST API for email"
description: "A documented REST API for your mailbox: 104 operations, an OpenAPI 3.1 spec you can read without a key, and keys you scope, rotate and revoke."
url: "https://openemail.uk/features/api"
---

[Agents, API & MCP](https://openemail.uk/features.md#agents)

# 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.

[Open mail](https://openemail.uk/mail/inbox) [Get Started](https://openemail.uk/signup.md)[All features](https://openemail.uk/features.md)

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.

emails:send Send mail emails:read Sent mail and its trail threads:write Label and archive templates:write Edit and send with templates webhooks:write Create and test webhooks keys:write Rotate its own secret

## Send your first email

Plain HTTP and JSON. Nothing to install.

202 while queued or scheduled, 200 once settled.

```
curl -X POST https://api.openemail.uk/emails \  -H "Authorization: Bearer $OPENEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "from": "Acme Billing <billing@acme.com>",    "to": ["ada@example.com"],    "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

1. 01
   
   One key per service
   
   Revoking a leaked key then stops one integration, not all of them.
2. 02
   
   Set an Idempotency-Key
   
   Derive it from something unique, like an invoice number, so a retry replays.
3. 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

Questions

## Asked often

Keep going

## Works well with

Typed SDKs

A TypeScript client first, then the rest.

Webhooks

Tell your endpoint when mail arrives, instead of making you poll.

MCP server

Point Claude, or any MCP client, at your mailbox.

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.

[Open mail](https://openemail.uk/mail/inbox) [Get Started](https://openemail.uk/signup.md)[Read the reference](https://openemail.uk/docs/knowledge/agents/api.md)