Postbag · Developers
Sending API
Quick start
- Start Postbag free, or add it to your Corantr account under Plan and billing.
- Add your domain under Sending domains, put the records it shows in your DNS, and press Check. Nothing can be sent until the domain is verified.
- Make a key under Postbag → API keys. It's shown once: keep it on your server.
- Send your first email:
curl https://desk.corantr.com/api/v1/postbag/emails \
-H "Authorization: Bearer pba_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.co.uk>",
"to": ["jo@example.com"],
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>"
}'
The answer is the email's id and its status: {"id": "019a7c2e-…", "status": "sent"}. Every address below is relative to https://desk.corantr.com/api/v1/postbag.
Keys
Send your key in the Authorization header as a bearer token. Owners of the account make keys under Postbag → API keys, and can delete one at any time; it stops working at once.
- Send email only keys can call the two sending addresses and nothing else. Use these in apps that just send.
- Full access keys can also read emails' status, your suppressions and your domains.
- A key can be limited to some of your sending domains.
Keys belong on your server. Never put one in a web page, a mobile app or anything else people can download.
Send an email
POST /emails
| Field | What it is |
|---|---|
from | Required. hello@acme.co.uk or Acme <hello@acme.co.uk>, on one of your verified sending domains. |
to | Required. An address, or a list of them. |
cc, bcc | Optional, as to. Ten recipients at most across to, cc and bcc. |
subject | Required. |
html, text | At least one. Without text, a plain-text version is made from the HTML. |
reply_to | Optional. An address, or a list. |
attachments | Optional. Up to 10, 7 MB in all: [{"filename": "invoice.pdf", "content": "<base64>", "content_type": "application/pdf"}]. Programs and scripts can't be attached. |
transactional | Optional, true or false (default false). Set true for a one-to-one email the recipient is expecting — a receipt, a password reset, a confirmation. Any other email is treated as bulk and carries a one-click unsubscribe (see below). |
headers | Optional. List-Unsubscribe, List-Unsubscribe-Post, List-Id and your own X- headers. Others are ignored. |
tags | Optional. Up to 10, as {"order": "1042"}. They come back on the email's status and on webhooks, so you can match them up. They're never sent to the recipient. |
One-click unsubscribe
Gmail, Yahoo and Microsoft expect bulk email to carry a one-click unsubscribe. So unless you send a single email with "transactional": true, we add a working List-Unsubscribe for you: one click adds that address to your suppression list, and you never email it again. We never override a List-Unsubscribe header you set yourself. Mark receipts, password resets and other expected one-to-one email as transactional so it carries none.
Sending twice by mistake
Add an Idempotency-Key header (your own id for the email, up to 256 characters). Sending again with the same key returns the first email's id and sends nothing more. If the first try failed with a 503, the same key may try again.
Suppressed addresses
Anyone on your suppression list is taken off the email before it's sent. If nobody is left, nothing is sent and the status is suppressed.
Send a batch
POST /emails/batch with a JSON list of up to 100 emails, each in the same shape as above. They're all checked first: if one is wrong, none is sent and the error says which (counting from 0). Otherwise they're queued and sent within moments.
{"data": [{"id": "019a7c2e-…"}, {"id": "019a7c2e-…"}]}
An Idempotency-Key works for a whole batch for a day.
Status
GET /emails/{id} returns an email and what happened to it:
{
"id": "019a7c2e-…",
"object": "email",
"from": "hello@acme.co.uk",
"to": "jo@example.com",
"recipients": 1,
"subject": "Your receipt",
"status": "delivered",
"tags": {"order": "1042"},
"created_at": "2026-11-15T10:04:31+00:00",
"sent_at": "2026-11-15T10:04:31+00:00",
"last_event_at": "2026-11-15T10:04:33+00:00",
"events": [
{"type": "sent", "at": "2026-11-15T10:04:31+00:00"},
{"type": "delivered", "at": "2026-11-15T10:04:33+00:00", "recipient": "jo@example.com"}
]
}
| Status | Means |
|---|---|
queued | Waiting to be sent (a batch). |
sent | Handed on for delivery. |
delivered | The receiving mail server accepted it. |
bounced | The address doesn't exist or refused it for good. It's now suppressed. |
complained | The recipient marked it as spam. They're now suppressed. |
suppressed | Not sent: every recipient was on your suppression list. |
failed | Not sent: it was refused. error says why. |
GET /emails lists your emails, newest first: limit (up to 100, 20 by default), before (an id, to carry on from), and status or to to filter. The answer has data and has_more. Emails are kept for 30 days (3 on the Free plan); you can see them in the app under Postbag → Activity too. Only who it went to, the subject and what happened are kept, never the email itself.
These need a full-access key.
Suppressions
Addresses your account never emails, whichever app, website or campaign sends: bounced, marked as spam, unsubscribed, or added by you. Bounces and spam reports are added for you.
GET /suppressions: newest first, withlimit,before(an address) andemailto look one up.POST /suppressionswith{"email": "…"}adds one.DELETE /suppressions/{email}removes one, so you can email it again. An address that marked your email as spam can't be removed.
GET /domains lists your sending domains and whether each can send.
Webhooks
Add an HTTPS address under Postbag → Webhooks and choose the events. Each event is a POST of JSON:
{
"id": "evt_01j…",
"type": "email.bounced",
"created_at": "2026-11-15T10:04:33+00:00",
"data": {
"email_id": "019a7c2e-…",
"from": "hello@acme.co.uk",
"to": "jo@example.com",
"subject": "Your receipt",
"tags": {"order": "1042"},
"recipient": "jo@example.com",
"bounce_type": "permanent",
"detail": "Permanent General: 550 No such user"
}
}
Events: email.sent, email.delivered, email.bounced (bounce_type is permanent or transient), email.complained, email.suppressed, email.failed, email.opened and email.clicked (only from a domain where you've switched tracking on), and sending.paused. The page's Send a test sends webhook.test.
Answer with any 2xx within 15 seconds. Anything else is tried again for about a day, with the same event id, so ignore an id you've already handled. An address that fails 10 events in a row is switched off and the account's owners are emailed.
Checking the signature
Each request has three headers: Corantr-Event-Id, Corantr-Timestamp (Unix seconds) and Corantr-Signature. The signature is v1, followed by the base64 HMAC-SHA256 of {id}.{timestamp}.{body}, keyed with your endpoint's signing secret: the part after whsec_, base64-decoded. Check it against the raw body, before parsing it, and refuse a timestamp more than five minutes old.
// PHP
$secret = base64_decode(substr(getenv('POSTBAG_WEBHOOK_SECRET'), 6));
$id = $_SERVER['HTTP_CORANTR_EVENT_ID'];
$ts = $_SERVER['HTTP_CORANTR_TIMESTAMP'];
$body = file_get_contents('php://input');
$expected = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (! hash_equals($expected, $_SERVER['HTTP_CORANTR_SIGNATURE']) || abs(time() - (int) $ts) > 300) {
http_response_code(400);
exit;
}
// Node
import crypto from 'node:crypto';
function verify(headers, rawBody, signingSecret) {
const key = Buffer.from(signingSecret.replace(/^whsec_/, ''), 'base64');
const id = headers['corantr-event-id'];
const ts = headers['corantr-timestamp'];
const expected = 'v1,' + crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
const given = headers['corantr-signature'] ?? '';
return given.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
&& Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
}
Errors
An error has a code to act on and a message to read: {"name": "validation_error", "code": "domain_not_verified", "message": "…"}.
| Status | Codes | What to do |
|---|---|---|
| 401 | invalid_api_key | Check the key, or make a new one. |
| 403 | restricted_key, domain_not_allowed, sending_paused, account_suspended, no_postbag | Not something a retry will fix. A pause is explained by email to the account's owners. |
| 404 | not_found | No such email or suppression on this account. |
| 422 | validation_error, domain_not_verified, domain_not_ready | Fix the request. Don't retry it as it is. |
| 429 | daily_limit, warmup_limit, monthly_limit, or too many requests | Wait for Retry-After seconds where it's given, or upgrade for a higher monthly limit. |
| 503 | application_error | Try again shortly, with the same Idempotency-Key. |
Limits
- 10 requests a second for each key.
- Email sent through the API counts towards your plan's emails a month, shared with your campaigns, and towards its emails a day, shared with your websites and assistants. Each recipient counts as one.
- New senders start slowly. For your first 14 days, the API sends up to 50 emails on day one, doubling each day while few bounce or are marked as spam. It's the same on every plan, and it's how mail providers come to trust a new sender.
- Sending pauses if, over the last 7 days, more than 4% of your email hard-bounces or more than 0.08% is marked as spam. Your owners are emailed at half those levels, while there's time to act.
| Plan | Price | Emails a month | A day | API keys | Webhooks | Activity kept |
|---|---|---|---|---|---|---|
| Free | Free | 2,000 | 100 | 2 | 1 | 3 days |
| Starter | £15 a month | 15,000 | 500 | 5 | 3 | 30 days |
| Growth | £39 a month | 60,000 | 2,000 | 20 | 10 | 30 days |
| Pro | £99 a month | 300,000 | 10,000 | Unlimited | Unlimited | 30 days |
Prices exclude VAT. See every plan.
Questions? Get in touch.