API reference

Who am I

get/v1/mescope: any key

The current organization, plan and usage, and the API key making the request. Call this first to check a key.

curl https://api.futuremail.dev/v1/me \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Me — OK

Send an email

post/v1/emailsscope: send · needs an active plan

Send now, or later with scheduledAt. from must be an address on one of your verified domains. To test without sending anything, address it to delivered@test.futuremail.dev (or bounced@, complained@, delayed@): test sends don't count toward your limits.

Body

curl -X POST https://api.futuremail.dev/v1/emails \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": "ada@example.com",
  "subject": "Welcome to Acme",
  "html": "<p>Hi Ada!</p>",
  "tags": [
    {
      "name": "campaign",
      "value": "welcome"
    }
  ]
}'

Returns 201 Message — The email, queued (or scheduled). Also: 409 idempotency_key_reused / idempotency_request_in_progress. 429 Rate limit or plan recipient cap reached.

Send up to 100 emails

post/v1/emails/batchscope: send · needs an active plan

Validated all-or-nothing: if any email is invalid nothing is sent and the error names it (3: to: …). Results are in input order.

Body — an array (1–100) of the email object below

curl -X POST https://api.futuremail.dev/v1/emails/batch \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "from": "hello@acme.com",
    "to": "ada@example.com",
    "subject": "Hi Ada",
    "text": "Hello!"
  },
  {
    "from": "hello@acme.com",
    "to": "grace@example.com",
    "subject": "Hi Grace",
    "text": "Hello!"
  }
]'

Returns 201 a list of Message — The emails, in input order.

List or search emails

get/v1/emailsscope: read

Newest first. q supports Gmail-style search: from: to: subject: has:attachment is:unread in:sent after:2026-09-01 newer_than:7d.

curl https://api.futuremail.dev/v1/emails \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Message — OK

Wait for an inbound email

get/v1/emails/waitscope: read

Long-poll until the next inbound email matching the filters arrives: ideal for sign-up confirmations and one-time codes (extracted.otp). Returns 204 on timeout.

curl https://api.futuremail.dev/v1/emails/wait \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Message — The matching email. Also: 204 Nothing arrived before the timeout.

Get an email

get/v1/emails/{id}scope: read

curl https://api.futuremail.dev/v1/emails/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Message — OK

Mark read or reschedule

patch/v1/emails/{id}scope: read

scheduledAt moves a scheduled email (needs the send scope); 409 not_scheduled once it's been sent.

Body

curl -X PATCH https://api.futuremail.dev/v1/emails/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduledAt": "2026-10-09T09:00:00Z"
}'

Returns 200 Message — OK

Cancel a scheduled email

post/v1/emails/{id}/cancelscope: send

curl -X POST https://api.futuremail.dev/v1/emails/<id>/cancel \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Message — The email, now canceled. Also: 409 not_scheduled: it was already sent or canceled.

Delivery timeline

get/v1/emails/{id}/eventsscope: read

Oldest first: queued → sent → delivered / bounced / complained / failed, plus opened and clicked when tracking is on.

curl https://api.futuremail.dev/v1/emails/<id>/events \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of EmailEvent — OK

Reply

post/v1/emails/{id}/replyscope: send · needs an active plan

Threads correctly (In-Reply-To/References) and quotes the original.

Body

curl -X POST https://api.futuremail.dev/v1/emails/<id>/reply \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Thanks, done!"
}'

Returns 201 Message — The reply.

Forward

post/v1/emails/{id}/forwardscope: send · needs an active plan

Attachments are included.

Body

curl -X POST https://api.futuremail.dev/v1/emails/<id>/forward \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "team@acme.com",
  "text": "FYI"
}'

Returns 201 Message — The forwarded email.

Raw RFC 822 source

get/v1/emails/{id}/rawscope: read

curl https://api.futuremail.dev/v1/emails/<id>/raw \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 message/rfc822 — The raw message.

Download an attachment

get/v1/attachments/{id}scope: read

curl https://api.futuremail.dev/v1/attachments/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 application/octet-stream — The file, with its content type.

List conversations

get/v1/threadsscope: read

curl https://api.futuremail.dev/v1/threads \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Thread — OK

Get a thread with its messages

get/v1/threads/{id}scope: read

curl https://api.futuremail.dev/v1/threads/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 ThreadWithMessages — OK

Archive, star or mark read

patch/v1/threads/{id}scope: read

Body

curl -X PATCH https://api.futuremail.dev/v1/threads/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "archived"
}'

Returns 200 Thread — OK

Update many threads

post/v1/threads/batchscope: read

Body

curl -X POST https://api.futuremail.dev/v1/threads/batch \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "thr_1",
    "thr_2"
  ],
  "read": true
}'

Returns 200 a list of Thread — OK

Delete a thread permanently

delete/v1/threads/{id}scope: read

curl -X DELETE https://api.futuremail.dev/v1/threads/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

List domains

get/v1/domainsscope: any key

curl https://api.futuremail.dev/v1/domains \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Domain — OK

Add a domain

post/v1/domainsscope: full · needs an active plan

Returns the DNS records to create (DKIM, MX, SPF, DMARC, MAIL FROM). Then call verify.

Body

curl -X POST https://api.futuremail.dev/v1/domains \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "acme.com"
}'

Returns 201 Domain — Created.

Get a domain

get/v1/domains/{id}scope: any key

curl https://api.futuremail.dev/v1/domains/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Domain — OK

Re-check DNS

post/v1/domains/{id}/verifyscope: full

Looks up every record now. sendingEnabled turns on when DKIM verifies, receivingEnabled when MX points at FutureMail.

curl -X POST https://api.futuremail.dev/v1/domains/<id>/verify \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Domain — OK

Domain settings

patch/v1/domains/{id}scope: full

Catch-all, custom MAIL FROM, TLS policy and open/click tracking.

Body

curl -X PATCH https://api.futuremail.dev/v1/domains/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "clickTracking": true,
  "openTracking": true
}'

Returns 200 Domain — OK

Remove a domain

delete/v1/domains/{id}scope: full

curl -X DELETE https://api.futuremail.dev/v1/domains/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

List addresses

get/v1/addressesscope: any key

curl https://api.futuremail.dev/v1/addresses \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Address — OK

Check an address

get/v1/addresses/availabilityscope: any key

Whether you can create this address (its domain must be one of yours).

curl https://api.futuremail.dev/v1/addresses/availability \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 AddressAvailability — OK

Create an address

post/v1/addressesscope: full · needs an active plan

Addresses are unlimited on your plan; each delivers into one mailbox.

Body

curl -X POST https://api.futuremail.dev/v1/addresses \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "support@acme.com",
  "displayName": "Acme Support"
}'

Returns 201 Address — Created.

Update an address

patch/v1/addresses/{id}scope: full

Body

curl -X PATCH https://api.futuremail.dev/v1/addresses/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Acme Help"
}'

Returns 200 Address — OK

Delete an address

delete/v1/addresses/{id}scope: full

curl -X DELETE https://api.futuremail.dev/v1/addresses/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

List mailboxes

get/v1/mailboxesscope: any key

curl https://api.futuremail.dev/v1/mailboxes \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Mailbox — OK

Create a mailbox

post/v1/mailboxesscope: full · needs an active plan

Body

curl -X POST https://api.futuremail.dev/v1/mailboxes \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support"
}'

Returns 201 Mailbox — Created.

Get a mailbox

get/v1/mailboxes/{id}scope: any key

curl https://api.futuremail.dev/v1/mailboxes/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Mailbox — OK

Update a mailbox

patch/v1/mailboxes/{id}scope: full

Body

curl -X PATCH https://api.futuremail.dev/v1/mailboxes/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "primaryAddress": "support@acme.com"
}'

Returns 200 Mailbox — OK

Delete a mailbox

delete/v1/mailboxes/{id}scope: full

curl -X DELETE https://api.futuremail.dev/v1/mailboxes/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

Provision an agent inbox

post/v1/agentsscope: full · needs an active plan

Creates an agent mailbox, an address and an API key pinned to that mailbox in one call. The key is returned once.

Body

curl -X POST https://api.futuremail.dev/v1/agents \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Signup bot",
  "address": "signup-bot@acme.com"
}'

Returns 201 AgentProvisioned — Created.

List templates

get/v1/templatesscope: any key

curl https://api.futuremail.dev/v1/templates \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Template — OK

Create a template

post/v1/templatesscope: full

Edits change the draft; sends use the last published version.

Body

curl -X POST https://api.futuremail.dev/v1/templates \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Welcome",
  "alias": "welcome",
  "subject": "Welcome, {{name}}!",
  "html": "<p>Hi {{name}}</p>",
  "variables": [
    {
      "key": "name",
      "fallback": "there"
    }
  ],
  "publish": true
}'

Returns 201 Template — Created.

Get a template

get/v1/templates/{id}scope: any key

curl https://api.futuremail.dev/v1/templates/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Template — OK

Edit the draft

patch/v1/templates/{id}scope: full

Body

curl -X PATCH https://api.futuremail.dev/v1/templates/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Welcome aboard, {{name}}!"
}'

Returns 200 Template — OK

Publish the draft

post/v1/templates/{id}/publishscope: full

curl -X POST https://api.futuremail.dev/v1/templates/<id>/publish \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Template — OK

Render with variables

post/v1/templates/{id}/renderscope: any key

Body

curl -X POST https://api.futuremail.dev/v1/templates/<id>/render \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "variables": {
    "name": "Ada"
  }
}'

Returns 200 RenderedTemplate — OK

Delete a template

delete/v1/templates/{id}scope: full

curl -X DELETE https://api.futuremail.dev/v1/templates/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

List suppressed addresses

get/v1/suppressionsscope: read

Addresses your org won't send to: permanent bounces and complaints are added automatically.

curl https://api.futuremail.dev/v1/suppressions \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Suppression — OK

Suppress addresses

post/v1/suppressionsscope: full

Body

curl -X POST https://api.futuremail.dev/v1/suppressions \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "old@example.com"
  ],
  "reason": "unsubscribe"
}'

Returns 201 AddSuppressionsResult — Added (200 when every address was already suppressed).

Check addresses

post/v1/suppressions/checkscope: read

Body

curl -X POST https://api.futuremail.dev/v1/suppressions/check \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "ada@example.com",
    "old@example.com"
  ]
}'

Returns 200 CheckSuppressionsResult — OK

Get a suppression

get/v1/suppressions/{email}scope: read

curl https://api.futuremail.dev/v1/suppressions/<email> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Suppression — OK

Remove a suppression

delete/v1/suppressions/{email}scope: full

curl -X DELETE https://api.futuremail.dev/v1/suppressions/<email> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

List API keys

get/v1/api-keysscope: full

curl https://api.futuremail.dev/v1/api-keys \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of ApiKey — OK

Create an API key

post/v1/api-keysscope: full · needs an active plan

The secret is returned once. Restrict keys to a mailbox, a sending domain and/or an expiry.

Body

curl -X POST https://api.futuremail.dev/v1/api-keys \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CI",
  "scopes": [
    "send"
  ],
  "expiresAt": "2027-01-01T00:00:00Z"
}'

Returns 201 ApiKeyWithSecret — Created.

Update an API key

patch/v1/api-keys/{id}scope: full

Expiry can't be changed: rotate the key instead.

Body

curl -X PATCH https://api.futuremail.dev/v1/api-keys/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CI (deploys)"
}'

Returns 200 ApiKey — OK

Revoke an API key

delete/v1/api-keys/{id}scope: full

curl -X DELETE https://api.futuremail.dev/v1/api-keys/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

List webhooks

get/v1/webhooksscope: full

curl https://api.futuremail.dev/v1/webhooks \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of Webhook — OK

Create a webhook

post/v1/webhooksscope: full · needs an active plan

Events are POSTed as { id, type, createdAt, data } with a FutureMail-Signature: t=<unix>,v1=<hex> header, where v1 = HMAC-SHA256(secret, <t>.<raw body>). Non-2xx responses are retried with backoff (8 attempts).

Body

curl -X POST https://api.futuremail.dev/v1/webhooks \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://acme.com/hooks/mail",
  "events": [
    "email.received",
    "email.bounced"
  ]
}'

Returns 201 Webhook — Created (includes the signing secret, shown once).

Update a webhook

patch/v1/webhooks/{id}scope: full

Body

curl -X PATCH https://api.futuremail.dev/v1/webhooks/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'

Returns 200 Webhook — OK

Delete a webhook

delete/v1/webhooks/{id}scope: full

curl -X DELETE https://api.futuremail.dev/v1/webhooks/<id> \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 Deleted — Deleted.

Send a test event

post/v1/webhooks/{id}/testscope: full

curl -X POST https://api.futuremail.dev/v1/webhooks/<id>/test \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 WebhookDelivery — OK

Delivery attempts

get/v1/webhooks/{id}/deliveriesscope: full

Newest first, with status codes, payloads and the next retry. Kept 30 days.

curl https://api.futuremail.dev/v1/webhooks/<id>/deliveries \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 a list of WebhookDelivery — OK

Replay a delivery

post/v1/webhooks/{id}/deliveries/{deliveryId}/replayscope: full

Re-sends the exact payload (same event id) now.

curl -X POST https://api.futuremail.dev/v1/webhooks/<id>/deliveries/<deliveryId>/replay \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 WebhookDelivery — OK

Realtime event stream

get/v1/eventsscope: read

Server-Sent Events for the current org: every webhook event plus thread.updated, as event: <type> / data: <json>. A ready event is sent first. Mailbox-pinned keys only see their mailbox.

curl https://api.futuremail.dev/v1/events \
  -H "Authorization: Bearer $FUTUREMAIL_API_KEY"

Returns 200 text/event-stream — An event stream.