Three lines of curl. You're sending.
A REST API for transactional email. Same infra as the dashboard — same reputation, same deliverability, same verified domains.
Authentication
Every request must carry a bearer token in the Authorization header. Keys start with je_ followed by 64 hex characters, and are shown once at creation — we store only a hash, so keep it somewhere safe. There is no separate test mode: every key sends real mail.
Authorization: Bearer je_3f9a…
Create keys under Settings → API keys in the dashboard, or POST /api-keys. Revoked keys stop working within five seconds. Sending through the API needs a paid plan; accounts in their free trial get 402.
A request that carries a key is answered as that key and nothing else. If the key does not sign in (unknown, revoked, expired, or an OAuth access token a refresh replaced), the request is refused with 401, and a dashboard page sends it to the sign-in page, even when the same request also carries a valid dashboard session cookie: the cookie is never used in place of the key.
Base URL
https://justemails.app/api/v1
All endpoints below are relative to this base. Every response is JSON. Success responses carry a 2xxstatus and a body with { "data": … }; error responses carry 4xx or 5xx plus a body with { "error": { "code", "message" } }.
Endpoints
Eight endpoints cover send, read, tracking settings and API-key management.
Code examples
Webhooks
Register an HTTPS endpoint under Settings → Webhooks and choose its events. Each delivery is a POST of { "event", "timestamp", "data" }. One that does not get a 2xx within 10 seconds is tried again 30s, 2m, 10m and then 1h after each failed attempt: five attempts in all, the last about 1h13m after the first.
One domain or all
A webhook gets every domain's events unless you limit it to one. Choose the domain when you add it under Settings → Webhooks, or send "domain": "example.com" (a verified domain's name, or its id) to POST /api/v1/webhooks. PATCH /api/v1/webhooks/{id} with {"domain": "example.com"} limits an existing one, and {"domain": null} opens it to every domain again.
A webhook limited to a domain gets email.received for mail stored in that domain's mailboxes, the email.* status, open and click events of API mail sent from that domain's addresses, and that domain's domain.drifted. An API key limited to one domain sees and manages only webhooks limited to its domain, and a webhook it adds without domain is limited to it. Such a key may keep at most 3 webhooks limited to its domains, counted together across them, whoever added them, and the account's own limit applies too. Deleting a domain deletes the webhooks limited to it.
Signatures
To verify a delivery, compute the HMAC-SHA256, keyed with the webhook's signing secret, of the timestamp, a dot, the delivery id, a dot and the raw body (the bytes as received, before any JSON parsing), and compare it with v1 in constant time. Refuse a timestamp more than 5 minutes from your clock. Then handle each delivery id once, and answer 2xx to one you have already handled: a retry keeps its id, and a replayed request inside the 5 minutes has the same id. Keeping handled ids for a day covers both.
Nothing in the signature says which webhook a delivery was sent to, so use a different secret for each webhook (we generate a new one for every webhook unless you choose your own), or keep one store of handled delivery ids for all the endpoints that share a secret. Otherwise a delivery sent to one of them can be replayed at another inside the 5 minutes, under an id that endpoint has never handled.
// Node 18+, no dependencies. headers: Node's req.headers (lowercase names).
// rawBody: the body exactly as received (a Buffer), before parsing the JSON.
import crypto from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
function verifyJustEmails(headers, rawBody, secret) {
const id = headers['x-justemails-delivery-id'] ?? '';
const v2 = headers['x-justemails-signature-v2'] ?? '';
const t = /(?:^|,)t=(\d+)(?:,|$)/.exec(v2)?.[1];
const v1 = /(?:^|,)v1=([0-9a-f]{64})(?:,|$)/.exec(v2)?.[1];
if (!t || !v1) return false;
// Too old, or too far ahead: a replay, or a clock that is off.
if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${id}.`)
.update(rawBody)
.digest();
return crypto.timingSafeEqual(Buffer.from(v1, 'hex'), expected);
}
// Then handle each delivery id once, and answer 2xx to one you have already
// handled: a retry keeps its id, and so does a replay inside the 5 minutes.
// Keep handled ids for a day (a unique key in your database does it).
// Nothing in the signature says which webhook a delivery was sent to, so use
// a different secret for each webhook (we generate a new one for every webhook
// unless you choose your own), or keep one store of handled delivery ids for
// all the endpoints that share a secret: otherwise a delivery sent to one of
// them can be replayed at another inside the 5 minutes.X-JustEmails-Signature is still sent, unchanged, so receivers that check it keep working. It signs the body alone and never expires: a delivery captured once verifies forever. Check X-JustEmails-Signature-V2 instead.
email.received
Metadata only — never the body. data.id is the stored email; fetch the body and attachments with GET /emails/{id} (same API key; add ?markRead=false to leave it unread). They are extracted a few seconds after the event fires, so an empty bodyHtml means retry shortly — and is why has_attachments is null in the event. data.to is the address this copy was delivered to (an alias or catch-all address when one was used), data.mailbox where it was stored, and data.folder inbox or spam. Sent only to the webhooks of the account that owns the domain and, for a webhook limited to one domain, only for that domain's mailboxes; in an organization, a member's personal mailbox fires nothing.
{
"event": "email.received",
"timestamp": "2026-10-01T09:20:11.502Z",
"data": {
"id": "6c1f0e9a-3b7d-4e52-9a1c-2f8e7d6c5b4a",
"message_id": "CAF=abc123@mail.gmail.com",
"mailbox": "support@yourdomain.com",
"from": "Alice Example <alice@example.com>",
"to": ["help@yourdomain.com"],
"subject": "Order 1042 never arrived",
"received_at": "2026-10-01T09:20:11.497Z",
"size_bytes": 48213,
"has_attachments": null,
"folder": "inbox",
"timestamp": "2026-10-01T09:20:11.497Z"
}
}Open and click tracking
Off by default, and only ever applied to mail sent through this API — never to mail from your mailboxes (webmail, IMAP/SMTP clients, forwarding). Turn it on for every send with PATCH /account/api-settings or in the dashboard, or per send with trackOpens / trackClicks, which override the default either way.
Only the HTML part changes. Opens add a 1×1 image; clicks rewrite each http(s) link to a signed https://justemails.app/t/c/… redirect that records the click and forwards to your link — and only to the link it was signed for. The plain-text part is sent exactly as written. Add data-je-notrack to an <a> to leave it alone. The rewrite happens before DKIM signing.
Each open or click is an opened / clicked event on the message (the click's detail is the link) and an email.opened / email.clicked webhook carrying the message's id, from, to, subject, tags and metadata, plus url for a click. We do not record the reader's IP address or device. Repeats within a minute count once; at most 50 opens and 50 clicks are recorded per message per hour.
Opens are approximate. Apple Mail Privacy Protection loads images on the reader's behalf, so opens are recorded that never happened; Gmail and other image proxies cache the image, so repeat opens are not seen; clients that block images record nothing. Link scanners can register clicks. With several recipients on one message, an open or click cannot be tied to one of them. You are responsible for any notice or consent your recipients' law requires.
Rate limits
Request rates are counted per client IP over the window shown. Sending limits are counted per account, across the dashboard and the API. Exceeding either returns 429 Too Many Requests with a Retry-After header telling you how long to back off, and an error.code naming the limit.
Error codes
Every error response carries a JSON body with error.code (machine-readable) and error.message (human).
140+ tools exposed via MCP.
Every action in the dashboard — domain add, DNS verify, alias create, forward rule, invoice fetch — is callable from any MCP-aware AI. Wire JustEmails into Claude, ChatGPT, Cursor, or any client that speaks the protocol.