Skip to content

Zorl Mail

Send and receive email on your own domains, with addresses, API keys and webhooks.

Invite only

Zorl Mail is open by invitation. It has two parts: an HTTPS API at https://mail.zorl.cloud, and a console for the same account on the same host. The API sends a message with one request to /v1/send. Mail that arrives for an address on one of your domains is kept for your account, shown in the console's inbox, readable through the API, and posted to a webhook if you register one.

Every API request carries an API key as a Bearer token and, when it has a body, sends JSON. Answers are JSON. An error is always an object with a code and a message; some carry a cause with more detail. The API is served on this host only: the same path on another Zorl host is answered 404, and the message names the address to use. Sending is done over HTTPS only: an API key is not an SMTP password.

Sending

Send one message with a POST to /v1/send. The key needs the mail:send scope, and the from address must be on a domain you verified, with DKIM verified too (see Domains and DNS).

curl -X POST https://mail.zorl.cloud/v1/send \
  -H "Authorization: Bearer zm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Your Name <[email protected]>",
    "to": "[email protected]",
    "subject": "Hello",
    "text": "Plain text body"
  }'

An accepted message is answered with 202:

{
  "id": "3f6c0f0e-6f1d-4c58-9f0b-2d1c2b7f4a10",
  "queuedAt": "2026-11-12T09:30:00.000Z",
  "messageId": "<[email protected]>",
  "warnings": [
    "DNS drift: No v=spf1 TXT record found on example.com. Add: 'v=spf1 ip4:178.105.145.41 -all'"
  ],
  "trace_url": "https://base.zorl.cloud/v1/tokens/mail_traces/..."
}
  • id names this send. The console shows the sent message under it, with its warnings and its trace link, for 30 days.
  • queuedAt is when the request was accepted.
  • messageId is the Message-ID header of the message that went out. Keep it if you want to match a reply to it later. It is left out when nothing went out.
  • warnings is a list of sentences about things that did not stop the send: recipients that were left out, a secret you chose to allow, or a DNS record of the sending domain that could not be found. It is left out when there is nothing to say.
  • trace_url is a link to a record of what was done with the request: the sender, the subject, the number of recipients, the first characters of the key, and the checks that ran. It does not hold the body or the recipients' addresses. Anyone who has the link can open it, and it works for 30 days. It is a note for you to look back at, not proof that a message was sent: the sent list in the console is the record of that.
  • sandbox_url is only there for a test send (see below).

Fields

The body is one JSON object. A field that is not in this table is refused with 400, so a misspelt field never goes missing quietly. There is no field for attachments.

FieldRequiredWhat it is
fromYesThe sender, as [email protected] or Your Name <[email protected]>. Any address on a domain you may send from works; it does not have to be an address you created.
toYesOne address, or a list of addresses. Addresses only, without names.
cc, bccNoThe same shape as to.
replyToNoOne address that replies should go to.
subjectYes1 to 998 characters, without line breaks.
text, htmlOne of themThe body, as plain text, as HTML, or both.
inReplyToNoThe Message-ID of the message this one answers, in angle brackets: <[email protected]>.
referencesNoThe Message-IDs of the conversation so far, each in angle brackets, separated by spaces. At most 4,096 characters, and 985 for one id.
headersNoYour own headers, as an object of name and value. Up to 10. A name starts with X-, continues with letters, digits and hyphens, is at most 64 characters long and does not start with X-Zorl-. A value is printable ASCII without line breaks. One header line (the name, a colon, a space and the value) is at most 998 characters, and all headers together at most 2,048 bytes.
tagsNoLabels of your own, as an object of name and text value. Up to 64, each value at most 256 characters. They are not put in the message.
idempotencyKeyNoA text of your choice, at most 128 characters, that makes a repeated request safe (see below).
allow_secretsNotrue or false. Sends a message even though the scan found a key or token in it (see below).
envNo"dev", "staging" or "prod". "dev" is a test send that delivers nothing. The other two, and leaving the field out, deliver.
categoryNo"transactional" or "bulk". A bulk message takes exactly one to address and no cc or bcc, and gets an unsubscribe link (see below).

A test send

With "env": "dev" nothing is delivered. The answer carries a sandbox_url: a page that shows the message as it would have been sent. The link works for 7 days and anyone who has it can open it. A test send skips the checks on the sending domain, the daily limit and the list of recipients that are left out, so you can try a request before your DNS is ready. A key that is limited to some domains is still held to them, and the scan for keys and tokens still runs.

curl -X POST https://mail.zorl.cloud/v1/send \
  -H "Authorization: Bearer zm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello",
    "html": "<p>Hello</p>",
    "env": "dev"
  }'

What is checked before a message goes out

For a real send, in this order:

  • The key may send from the domain of from. If not: 403, AUTHORIZATION.
  • The domain is one your account verified. If not: 403, AUTHORIZATION.
  • DKIM is verified for the domain. If not: 403, DELIVERY_REJECTED.
  • Sending is not switched off for the account. If it is: 423, DELIVERY_REJECTED.
  • The account is under its daily limit. If not: 429, RATE_LIMIT, with a Retry-After header.
  • Recipients that must not be mailed again are left out (next heading), and the body is scanned for keys and tokens (the heading after).

Recipients that are left out

Zorl Mail keeps a list, per account, of addresses that must not be mailed again: an address that unsubscribed, one whose mail came back because the address does not exist, and one that reported a message as spam. Mail that came back for a passing reason, such as a full mailbox, does not put an address on the list. A real send leaves the listed recipients out and names them in warnings, with the reason. If no recipient is left, the answer is still 202, nothing is delivered, there is no messageId, and warnings says so.

Bulk mail and unsubscribing

A message sent with "category": "bulk" goes out with a List-Unsubscribe header and a List-Unsubscribe-Post header, which is what mail programs use to show an unsubscribe button. The link is made for that one recipient, which is why a bulk message takes one recipient: send one request per person. Opening the link shows a page that asks for confirmation; confirming, or the mail program's own one-click request, puts the address on the list above for your account.

The scan for keys and tokens

Before a message is accepted, its subject, body, tags and headers are scanned for things that look like credentials: keys of Stripe, AWS, GitHub, OpenAI, Anthropic, Google, Slack, npm, PyPI, Twilio and SendGrid, Sentry addresses that carry a key, sign-in tokens (JWT), private keys, and Postgres or MongoDB addresses that carry a password. A message with one in it is refused with 400:

{
  "code": "BLOCKED_SECRET_LEAK",
  "message": "Email contains 1 detected secret. Send blocked. Set allow_secrets: true to override.",
  "cause": {
    "detections": [
      {
        "type": "github_token",
        "location": "text",
        "evidence": "ghp_Ab1A***",
        "remediationUrl": "https://github.com/settings/tokens"
      }
    ]
  }
}

The evidence is masked, so the answer does not repeat the secret. If the message is meant to carry it, send again with "allow_secrets": true: the message goes out and warnings lists what was found.

Sending the same request twice

Give a request an idempotencyKey and a repeat of it will not send a second message. Zorl Mail remembers a key for 72 hours.

  • The same key with the same body gets the first answer again, with the same id.
  • The same key with a different body is refused: 409, INVALID_INPUT.
  • The same key while the first request is still being sent is refused: 409, IDEMPOTENCY_IN_PROGRESS, with a Retry-After header. Ask again after that many seconds to get the first request's answer.
  • When a request with a key is answered 502 and Zorl Mail cannot tell whether the mail servers took the message (a timeout or a dropped connection), later requests with that key get 409, IDEMPOTENCY_OUTCOME_UNKNOWN. Check the sent list in the console, then send again with a new key if the message did not go out. After a clear refusal from the mail servers, the key can be used again.

A request that was refused before sending (a wrong field, a blocked secret) does not use the key up, so you can correct it and send again with the same key.

Replies

To answer a message so that mail programs keep the conversation together, set inReplyTo to the Message-ID of the message you answer and references to the ids of the conversation. A received message gives you both (see Receiving).

curl -X POST https://mail.zorl.cloud/v1/send \
  -H "Authorization: Bearer zm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Re: Question",
    "text": "Thanks for writing.",
    "inReplyTo": "<[email protected]>",
    "references": "<[email protected]>",
    "idempotencyKey": "reply-to-abc123"
  }'

Status codes

An error looks like this:

{
  "code": "INVALID_INPUT",
  "message": "subject is required"
}
StatusCodeWhen
202The message was accepted.
400INVALID_INPUTThe body is not JSON, a field is missing or wrong, or there is a field that does not exist. The message says which.
400BLOCKED_SECRET_LEAKThe scan found a key or token.
401AUTHORIZATIONThere is no Authorization header, it is not a Bearer token, or the key is unknown, revoked or expired.
403AUTHORIZATIONThe key lacks mail:send, the key may not send from this domain, or the domain is not one your account verified.
403DELIVERY_REJECTEDDKIM is not verified for the sending domain.
409INVALID_INPUTThe idempotencyKey was used before with a different body.
409IDEMPOTENCY_IN_PROGRESSA request with this key is being sent right now.
409IDEMPOTENCY_OUTCOME_UNKNOWNAn earlier request with this key may or may not have gone out.
423DELIVERY_REJECTEDSending is switched off for the account.
429RATE_LIMITToo many requests in a minute, or the daily limit is reached. Retry-After says how many seconds to wait.
502PROVIDER_DOWNThe mail servers did not take the message. Nothing was counted against the daily limit.
502AUTHORIZATIONZorl Mail could not sign in to its mail servers. Nothing went out. This is on Zorl's side.
500UNKNOWNMessage could not be built: Zorl Mail could not put the message together. Nothing went out, and the key can be used again.
503PROVIDER_DOWN, IDEMPOTENCY_UNAVAILABLESomething Zorl Mail needs could not be reached. Nothing was sent. Try again shortly.

Receiving

A domain receives mail once three things are true: the domain is verified, its MX record points at Zorl Mail, and the address exists (see Domains and DNS and Addresses). Mail for an address you have not created does not reach the inbox.

A message sent to [email protected] arrives at [email protected], and the part after the plus sign is kept as the message's tag.

Mail that is held back

A message with something wrong about it is still stored, but it is held back from the inbox and filed under Spam. In the API it has scope "quarantine" and a quarantine_reason:

ReasonWhat happened
unknown_addressThe message was for an address that does not exist on your domain.
auth_failedThe message failed DMARC: it is probably not from the sender it names.
spamThe mail servers scored the message as spam.
scan_failedThe message could not be checked for viruses. Its attachments cannot be downloaded.

The inbox

The console's inbox shows received mail in three folders: Inbox, Spam and Trash. You can show one address or one domain at a time, search, show unread mail only, mark messages as spam or not spam, and block a sender, whose later mail is then filed under Spam. A message in Trash is deleted for good after 30 days. Attachments are downloaded from the message's page in the console.

Folders belong to the console. Moving a message to Spam or Trash, or blocking its sender, does not change what the API returns for it; a message is gone from the API when it has been deleted for good.

Reading mail through the API

GET /v1/inbound/messages lists the account's received mail, oldest first. The key needs the mail:inbound:read scope.

curl "https://mail.zorl.cloud/v1/inbound/messages?since=2026-11-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer zm_your_key"
ParameterWhat it is
sinceOnly messages received at or after this time. An ISO 8601 date or time, such as 2026-11-01 or 2026-11-01T00:00:00Z.
limitHow many messages a page may hold, up to 100. A larger number is read as 100. Without it, 50.
cursorThe next_cursor of the page before, exactly as it was given.
{
  "messages": [
    {
      "storage_key": "mid:[email protected]:[email protected]",
      "message_id": "<[email protected]>",
      "received_at": "2026-11-12T09:31:07.412Z",
      "from": "\"Ann Lee\" <[email protected]>",
      "from_address": "[email protected]",
      "from_name": "Ann Lee",
      "to": ["[email protected]"],
      "cc": [],
      "envelope_to": "[email protected]",
      "delivered_to": "[email protected]",
      "tag": null,
      "subject": "Question",
      "text": "Hello,\n\nDo you have a moment?\n",
      "html": "",
      "in_reply_to": null,
      "references": [],
      "auto_submitted": null,
      "precedence": null,
      "scope": "tenant",
      "quarantine_reason": null,
      "auth_failed": false,
      "attachment_count": 0,
      "truncated": false,
      "body_truncated": false
    }
  ],
  "next_cursor": null
}

When next_cursor is not null there is more: ask again with it as cursor. When it is null you have everything up to now. A page also ends early, with a cursor, when the bodies in it would pass 3,000,000 bytes. A message can also carry a field that is not in this table; you can ignore it.

FieldWhat it is
storage_keyThe name of the message in Zorl Mail. Use it to read or delete this one message.
message_idThe Message-ID header, in angle brackets, or null.
received_atWhen Zorl Mail took the message.
from, from_address, from_nameThe From header as written, then its address and its name on their own. The name is null when there is none.
to, ccThe addresses in the To and Cc headers.
envelope_to, delivered_to, tagThe address the message was really sent to, the same address without its plus tag, and the tag. These can differ from to, for a blind copy for example.
subject, text, htmlThe subject and the two bodies. A body the message does not have is an empty text.
in_reply_to, referencesThe Message-ID this message answers, or null, and the ids of the conversation as a list.
auto_submitted, precedenceThe values of the Auto-Submitted and Precedence headers, or null. They tell an automatic message from one a person wrote, which matters before you send an automatic answer.
scope, quarantine_reason, auth_failed"tenant" for mail in the inbox, "quarantine" for mail that was held back, with the reason. auth_failed is true when the message failed DMARC.
attachment_countHow many attachments the message has. The API does not return the attachments themselves.
truncatedTrue when the message was too large to keep whole, and its bodies were shortened when it arrived.
body_truncatedTrue when text and html were shortened in this answer.

In a list, the two bodies of one message together are at most 900,000 bytes. Past that both are shortened and body_truncated is true. To get the whole message, read it on its own:

curl "https://mail.zorl.cloud/v1/inbound/messages/mid%3Ahello%40example.com%3Aabc123%40example.org" \
  -H "Authorization: Bearer zm_your_key"

The last part of the path is the storage_key, URL-encoded (it contains colons and at signs). The answer is the one message, in the same shape as in a list, with bodies up to 4,000,000 bytes.

To delete a message for good, send a DELETE to the same address with a key that has the mail:inbound:delete scope. The answer is 204 with no body. The message and its attachments are gone and cannot be brought back.

curl -X DELETE "https://mail.zorl.cloud/v1/inbound/messages/mid%3Ahello%40example.com%3Aabc123%40example.org" \
  -H "Authorization: Bearer zm_your_key"
StatusCodeWhen
200The list, or the one message.
204The message was deleted.
400INVALID_INPUTsince, limit or cursor is not valid.
401AUTHORIZATIONNo key, or a key that is unknown, revoked or expired.
403AUTHORIZATIONThe key lacks the scope the request needs.
404NOT_FOUNDThere is no such message for this key. A message of another account, and one outside the domains the key is limited to, look the same.
429RATE_LIMITToo many requests in a minute. Retry-After says how many seconds to wait.

A key that is limited to some domains only sees mail that was delivered to those domains.

Domains and DNS

You send from, and receive at, domains you own. Add a domain on the console's Domains page. It starts as pending, and the page shows one DNS record that proves the domain is yours:

_zorl-verify.example.com   TXT   zorl-verify-...

Publish it at your DNS provider, then press Verify. The record name is _zorl-verify, with the underscore, under your domain; the value is the token exactly as the console shows it. A domain can belong to one account only.

A verified domain shows four more records, in two groups, Receiving and Sending. The console reads your DNS every time the page loads and marks a record it cannot find as missing, so the page tells you what is still to do. Copy the values from the console: the DKIM record is different for every domain.

RecordNameValueWhat it is for
MXexample.com10 smtp.zorl.cloudReceiving. It sends mail for your domain to Zorl Mail. Without it nothing arrives.
DKIM (TXT)zmail-1a2b3c4d._domainkey.example.comv=DKIM1; k=rsa; p=...Sending. It holds the public key that receivers use to check the signature on your mail. The first part of the name is the selector the console gives your domain.
SPF (TXT)example.comv=spf1 ip4:178.105.145.41 -allSending. It names the address Zorl Mail sends from as allowed to send for your domain.
DMARC (TXT)_dmarc.example.comv=DMARC1; p=quarantine; adkim=s; aspf=s; rua=mailto:[email protected]Sending. It tells receivers what to do with mail that fails the two checks above, and where to send reports.

After the DKIM record is published, press Verify DKIM. Until DKIM is verified, a real send from the domain is refused with 403; a test send with "env": "dev" works before that. A send from a domain that is still pending is refused as well.

A verified domain without any address receives nothing, and its card says so. Pressing Re-check receiving on such a domain creates postmaster for it. Removing a domain on the same page stops both directions: sends from it are refused and its mail no longer reaches the account.

Addresses

An address is what makes a domain receive mail for one name. Create addresses on the console's Addresses page, on a verified domain. An address has:

  • a name, the part before the at sign: up to 64 letters, digits, dots, underscores, plus signs and hyphens, kept in lower case. The name bounces is taken on every domain, for undeliverable mail coming back;
  • a role, one of general, support, sales, billing, admin, noreply and custom. It is a label for you;
  • an optional label of your own.

A new address receives mail at once. Removing an address stops mail for it; for 30 days it is listed under Recently removed on the same page and can be restored.

Addresses are about receiving. Sending does not need one: any from address on a domain you may send from is accepted.

Webhooks

A webhook is an address of yours that Zorl Mail posts each received message to, as signed JSON, a moment after the message arrives. Mail that was held back is posted too, marked as such. Register a webhook on the console's Webhooks page, or through the API with a key that has the mail:webhooks:manage scope:

curl -X POST https://mail.zorl.cloud/v1/inbound/webhooks \
  -H "Authorization: Bearer zm_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/zorl", "domain": "example.com" }'
  • url must start with https://, name a public host (a name, not an IP address), carry no user name or password, use port 443 or 8443, and be at most 2,048 characters long.
  • domain is one of your domains, to get that domain's mail only. Leave it out, or send null, to get the mail of every domain. A key that is limited to some domains must name one of them.

The answer is 201 with the webhook and its signing secret. The secret is shown this one time. Store it: afterwards only its first characters (secret_prefix) are shown.

{
  "id": "5b0d7f0a-93f1-4d0e-8a56-1e0c2d9b7f31",
  "url": "https://hooks.example.com/zorl",
  "domain": "example.com",
  "enabled": true,
  "disabled_at": null,
  "disabled_reason": null,
  "secret_prefix": "whsec_Ab12Cd",
  "created_at": "2026-11-12T09:40:00.000Z",
  "last_success_at": null,
  "last_failure_at": null,
  "last_error": null,
  "consecutive_failures": 0,
  "secret": "whsec_your_secret"
}

An account can have 10 webhooks. The same URL cannot be registered twice for the same domain.

# list
curl https://mail.zorl.cloud/v1/inbound/webhooks -H "Authorization: Bearer zm_your_key"

# send a test event
curl -X POST https://mail.zorl.cloud/v1/inbound/webhooks/5b0d7f0a-93f1-4d0e-8a56-1e0c2d9b7f31/test \
  -H "Authorization: Bearer zm_your_key"

# delete
curl -X DELETE https://mail.zorl.cloud/v1/inbound/webhooks/5b0d7f0a-93f1-4d0e-8a56-1e0c2d9b7f31 \
  -H "Authorization: Bearer zm_your_key"

The list is { "webhooks": [ ... ] }, each in the shape above without secret. Deleting answers 204; DELETE /v1/inbound/webhooks?id=... does the same. A test posts one event of type mail.inbound.test with an empty data object to the URL, signed like a real one, and reports what your endpoint did:

{
  "ok": true,
  "status": 200,
  "error": null,
  "reason": null,
  "duration_ms": 41
}

When the test fails, ok is false, status is what your endpoint answered (or null when it did not answer), error is a sentence, and reason is a short word for it, such as status, redirect, timeout or dns.

What a delivery looks like

POST /zorl HTTP/1.1
Content-Type: application/json
User-Agent: Zorl-Webhooks/1
Zorl-Webhook-Id: 0c4f6c0e-2a7b-4a53-9d0f-8a1b6f3e5d27
Zorl-Webhook-Timestamp: 1794562267
Zorl-Webhook-Signature: v1=5d41402abc4b2a76b9719d911017c592ae2b7a0e4f3c1d5e6f708192a3b4c5d6

{
  "type": "mail.inbound",
  "id": "0c4f6c0e-2a7b-4a53-9d0f-8a1b6f3e5d27",
  "created_at": "2026-11-12T09:31:07.519Z",
  "data": { "storage_key": "mid:[email protected]:[email protected]", "subject": "Question", "...": "..." }
}

data is the message, in exactly the shape the API returns it (see Receiving). Its two bodies together are at most 900,000 bytes; when data.body_truncated is true, read the whole message with GET /v1/inbound/messages/<storage_key>.

Answer with any 2xx status within 5 seconds. Anything else counts as a failure: another status, no answer in time, or a redirect, which is not followed.

Checking the signature

Every delivery is signed with the webhook's secret, so you can tell it came from Zorl Mail. Take the value of Zorl-Webhook-Timestamp, a dot, and the body exactly as it arrived. Compute HMAC-SHA256 over that with the whole secret (including whsec_) as the key. The header Zorl-Webhook-Signature is v1= followed by the result in lowercase hex. Refuse a timestamp that is more than five minutes from your own clock.

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: the whole "whsec_..." string. rawBody: the request body exactly as it arrived.
export function isFromZorl(secret, headers, rawBody) {
  const timestamp = headers["zorl-webhook-timestamp"];
  const signature = headers["zorl-webhook-signature"];
  if (!/^\d+$/.test(timestamp ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "v1=" + createHmac("sha256", secret).update(timestamp + "." + rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Retries

A delivery that fails is tried again after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours: 7 attempts in all. Every attempt for the same message carries the same Zorl-Webhook-Id, which is also the event's id, so keep the ids you have handled and skip one you see again. After the last attempt the delivery is given up; the message itself stays in the inbox and in the API.

A webhook whose attempts fail 50 times in a row is switched off, and the deliveries still waiting for it are dropped. Mail that arrives while it is off is not posted. The Webhooks page shows the reason, the recent deliveries, and a switch to turn the webhook on again. A test event works on a webhook that is switched off, and never counts as a failure.

StatusCodeWhen
200The list, or the result of a test.
201The webhook was created.
204The webhook was deleted.
400INVALID_INPUTThe body is not a JSON object, has a field other than url and domain, the URL is not accepted, the domain is not yours, or the same webhook exists already.
401AUTHORIZATIONNo key, or a key that is unknown, revoked or expired.
403AUTHORIZATIONThe key lacks mail:webhooks:manage.
403FORBIDDENThe key is limited to some domains and the request did not name one of them.
404NOT_FOUNDThere is no such webhook for this key.
409LIMITThe account already has 10 webhooks.
429RATE_LIMITToo many requests in a minute, more than 10 webhooks created in 10 minutes, or more than 20 test events in 10 minutes.

API keys

A key says which account a request is for and what it may do. Make keys on the console's API keys page. The whole key is shown once, right after it is made; afterwards the page only shows its first 12 characters. Keep the key where you keep other secrets. A Mail key starts with zm_, then live, test or dev. That word is part of the key's name, so you can tell your keys apart; it does not change what the key does.

Authorization: Bearer zm_your_key

A key has a label (1 to 128 characters), one or more scopes, and optionally a list of domains.

ScopeWhat it allows
mail:sendSending with POST /v1/send.
mail:inbound:readReading received mail with GET /v1/inbound/messages.
mail:inbound:deleteDeleting received mail for good with DELETE /v1/inbound/messages.
mail:webhooks:manageCreating, listing, testing and deleting webhooks under /v1/inbound/webhooks.

A key with domains ticked may send only from those domains, sees only the mail delivered to them, and manages only their webhooks. A key with no domain ticked works for every domain of the account. The domains of a key can be changed later on the same page, without making a new key.

Revoking a key takes effect at once: the next request with it is answered 401. A request with a key that lacks the scope it needs is answered 403, and the message names the scope.

Limits

WhatLimit
Requests to /v1/send120 a minute for one key. Past that: 429 with Retry-After.
Messages a day200 for a new account, counted per request that goes out, from 00:00 UTC. Past that: 429 with Retry-After. Test sends are not counted.
Subject998 characters.
Your own headers10, with 2,048 bytes in all.
Tags64, each value 256 characters.
Idempotency key128 characters, remembered for 72 hours.
Test send link7 days.
Trace link, and the record of a sent message in the console30 days.
Requests to the inbound API120 a minute for one key, counting messages and webhooks together.
Messages in one list page100, and 50 when you do not ask.
Bodies in a list and in a webhook event900,000 bytes for one message.
Bodies of one message read on its own4,000,000 bytes.
Webhooks10 for one account.
Webhooks created10 in 10 minutes for one account.
Test events20 in 10 minutes for one account.
Time to answer a webhook delivery5 seconds.
Attempts for one webhook delivery7, then it is given up.
Failed attempts in a row before a webhook is switched off50.
Keys made10 in 10 minutes for one account.
Mail in TrashDeleted for good after 30 days.
A removed addressCan be restored for 30 days.

See also Accounts and sign-in for signing in to the console.