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/..."
}idnames this send. The console shows the sent message under it, with its warnings and its trace link, for 30 days.queuedAtis when the request was accepted.messageIdis 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.warningsis 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_urlis 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_urlis 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.
| Field | Required | What it is |
|---|---|---|
from | Yes | The 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. |
to | Yes | One address, or a list of addresses. Addresses only, without names. |
cc, bcc | No | The same shape as to. |
replyTo | No | One address that replies should go to. |
subject | Yes | 1 to 998 characters, without line breaks. |
text, html | One of them | The body, as plain text, as HTML, or both. |
inReplyTo | No | The Message-ID of the message this one answers, in angle brackets: <[email protected]>. |
references | No | The Message-IDs of the conversation so far, each in angle brackets, separated by spaces. At most 4,096 characters, and 985 for one id. |
headers | No | Your 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. |
tags | No | Labels 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. |
idempotencyKey | No | A text of your choice, at most 128 characters, that makes a repeated request safe (see below). |
allow_secrets | No | true or false. Sends a message even though the scan found a key or token in it (see below). |
env | No | "dev", "staging" or "prod". "dev" is a test send that delivers nothing. The other two, and leaving the field out, deliver. |
category | No | "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 aRetry-Afterheader. - 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 aRetry-Afterheader. Ask again after that many seconds to get the first request's answer. - When a request with a key is answered
502and Zorl Mail cannot tell whether the mail servers took the message (a timeout or a dropped connection), later requests with that key get409,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"
}| Status | Code | When |
|---|---|---|
| 202 | The message was accepted. | |
| 400 | INVALID_INPUT | The body is not JSON, a field is missing or wrong, or there is a field that does not exist. The message says which. |
| 400 | BLOCKED_SECRET_LEAK | The scan found a key or token. |
| 401 | AUTHORIZATION | There is no Authorization header, it is not a Bearer token, or the key is unknown, revoked or expired. |
| 403 | AUTHORIZATION | The key lacks mail:send, the key may not send from this domain, or the domain is not one your account verified. |
| 403 | DELIVERY_REJECTED | DKIM is not verified for the sending domain. |
| 409 | INVALID_INPUT | The idempotencyKey was used before with a different body. |
| 409 | IDEMPOTENCY_IN_PROGRESS | A request with this key is being sent right now. |
| 409 | IDEMPOTENCY_OUTCOME_UNKNOWN | An earlier request with this key may or may not have gone out. |
| 423 | DELIVERY_REJECTED | Sending is switched off for the account. |
| 429 | RATE_LIMIT | Too many requests in a minute, or the daily limit is reached. Retry-After says how many seconds to wait. |
| 502 | PROVIDER_DOWN | The mail servers did not take the message. Nothing was counted against the daily limit. |
| 502 | AUTHORIZATION | Zorl Mail could not sign in to its mail servers. Nothing went out. This is on Zorl's side. |
| 500 | UNKNOWN | Message could not be built: Zorl Mail could not put the message together. Nothing went out, and the key can be used again. |
| 503 | PROVIDER_DOWN, IDEMPOTENCY_UNAVAILABLE | Something 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:
| Reason | What happened |
|---|---|
unknown_address | The message was for an address that does not exist on your domain. |
auth_failed | The message failed DMARC: it is probably not from the sender it names. |
spam | The mail servers scored the message as spam. |
scan_failed | The 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"| Parameter | What it is |
|---|---|
since | Only messages received at or after this time. An ISO 8601 date or time, such as 2026-11-01 or 2026-11-01T00:00:00Z. |
limit | How many messages a page may hold, up to 100. A larger number is read as 100. Without it, 50. |
cursor | The 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.
| Field | What it is |
|---|---|
storage_key | The name of the message in Zorl Mail. Use it to read or delete this one message. |
message_id | The Message-ID header, in angle brackets, or null. |
received_at | When Zorl Mail took the message. |
from, from_address, from_name | The From header as written, then its address and its name on their own. The name is null when there is none. |
to, cc | The addresses in the To and Cc headers. |
envelope_to, delivered_to, tag | The 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, html | The subject and the two bodies. A body the message does not have is an empty text. |
in_reply_to, references | The Message-ID this message answers, or null, and the ids of the conversation as a list. |
auto_submitted, precedence | The 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_count | How many attachments the message has. The API does not return the attachments themselves. |
truncated | True when the message was too large to keep whole, and its bodies were shortened when it arrived. |
body_truncated | True 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"| Status | Code | When |
|---|---|---|
| 200 | The list, or the one message. | |
| 204 | The message was deleted. | |
| 400 | INVALID_INPUT | since, limit or cursor is not valid. |
| 401 | AUTHORIZATION | No key, or a key that is unknown, revoked or expired. |
| 403 | AUTHORIZATION | The key lacks the scope the request needs. |
| 404 | NOT_FOUND | There 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. |
| 429 | RATE_LIMIT | Too 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.
| Record | Name | Value | What it is for |
|---|---|---|---|
| MX | example.com | 10 smtp.zorl.cloud | Receiving. It sends mail for your domain to Zorl Mail. Without it nothing arrives. |
| DKIM (TXT) | zmail-1a2b3c4d._domainkey.example.com | v=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.com | v=spf1 ip4:178.105.145.41 -all | Sending. It names the address Zorl Mail sends from as allowed to send for your domain. |
| DMARC (TXT) | _dmarc.example.com | v=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
bouncesis taken on every domain, for undeliverable mail coming back; - a role, one of
general,support,sales,billing,admin,noreplyandcustom. 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" }'urlmust start withhttps://, 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.domainis one of your domains, to get that domain's mail only. Leave it out, or sendnull, 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.
| Status | Code | When |
|---|---|---|
| 200 | The list, or the result of a test. | |
| 201 | The webhook was created. | |
| 204 | The webhook was deleted. | |
| 400 | INVALID_INPUT | The 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. |
| 401 | AUTHORIZATION | No key, or a key that is unknown, revoked or expired. |
| 403 | AUTHORIZATION | The key lacks mail:webhooks:manage. |
| 403 | FORBIDDEN | The key is limited to some domains and the request did not name one of them. |
| 404 | NOT_FOUND | There is no such webhook for this key. |
| 409 | LIMIT | The account already has 10 webhooks. |
| 429 | RATE_LIMIT | Too 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_keyA key has a label (1 to 128 characters), one or more scopes, and optionally a list of domains.
| Scope | What it allows |
|---|---|
mail:send | Sending with POST /v1/send. |
mail:inbound:read | Reading received mail with GET /v1/inbound/messages. |
mail:inbound:delete | Deleting received mail for good with DELETE /v1/inbound/messages. |
mail:webhooks:manage | Creating, 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
| What | Limit |
|---|---|
| Requests to /v1/send | 120 a minute for one key. Past that: 429 with Retry-After. |
| Messages a day | 200 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. |
| Subject | 998 characters. |
| Your own headers | 10, with 2,048 bytes in all. |
| Tags | 64, each value 256 characters. |
| Idempotency key | 128 characters, remembered for 72 hours. |
| Test send link | 7 days. |
| Trace link, and the record of a sent message in the console | 30 days. |
| Requests to the inbound API | 120 a minute for one key, counting messages and webhooks together. |
| Messages in one list page | 100, and 50 when you do not ask. |
| Bodies in a list and in a webhook event | 900,000 bytes for one message. |
| Bodies of one message read on its own | 4,000,000 bytes. |
| Webhooks | 10 for one account. |
| Webhooks created | 10 in 10 minutes for one account. |
| Test events | 20 in 10 minutes for one account. |
| Time to answer a webhook delivery | 5 seconds. |
| Attempts for one webhook delivery | 7, then it is given up. |
| Failed attempts in a row before a webhook is switched off | 50. |
| Keys made | 10 in 10 minutes for one account. |
| Mail in Trash | Deleted for good after 30 days. |
| A removed address | Can be restored for 30 days. |
See also Accounts and sign-in for signing in to the console.