EmailPal API

Everything needed to know whether a create will succeed before attempting it. A 402 halfway through a batch of forty mailboxes leaves you working out which ones landed, so the intended pattern is to read this, size the batch, and then send it.

It also carries domain_balance_cents, which is the figure a domain purchase is charged against. That is a separate pot from the subscription card and has to cover the whole batch before any of it is bought.

usage.warming_mailboxes is counted per inbox rather than per mailbox we host, so it includes addresses connected from Gmail, Microsoft or your own server as well as mailboxes here. It will not equal usage.mailboxes.used in either direction.

Returns a hosted payment page. Nothing is charged by this call: the balance goes up when the processor confirms the payment, which is usually a second or two after somebody completes that page.

This exists so an integration that hits insufficient_balance on a purchase has somewhere to go. Without it the automation ends in an email to a human who then has to find the dashboard.

admin scope rather than write, because spending money is not the same permission as creating a mailbox, and a key handed to a provisioning script should not be able to run up a card.

Newest first. Filter by status to answer a specific question: needs_dns for domains waiting on somebody to delegate nameservers, aging for inventory not yet old enough to send from, ready and active for the ones that can take mailboxes.

Read dns_method before nameservers_verified. Delegation only applies to the nameservers method, so on a manual or cloudflare_token domain that flag stays false however healthy the domain is, and treating it as a readiness signal would report a working domain as broken.

One endpoint with a mode, rather than two URLs. Buying and connecting produce the same kind of row and are genuinely different acts, and splitting them across two paths would let a client that meant to connect accidentally spend money at a registrar.

mode: "purchase" prices the whole batch against the registrar, takes the total off the domain balance, and only then queues the registrations. If the balance will not cover all of it, nothing is bought and you get a 402 carrying the shortfall — a partial charge against a partial result is the thing worth avoiding here. Registrations that then fail are refunded to the balance automatically.

mode: "connect" costs nothing, and takes a dns_method saying how the records are going to get written. nameservers (the default) creates the zone in our Cloudflare and hands back nameservers to delegate to. manual writes nothing anywhere: we compute the records, list them on GET /domains/{id}, and you add them at whatever DNS host you already use. Either way the domain sits in needs_dns until public DNS agrees, which is expected rather than a failure.

The third method, cloudflare_token, is not available here — the token has to be proved against the zone before it is worth storing, so it goes to POST /domains/{id}/cloudflare-token once the domain exists. Create the domain as manual and attach the token after, or just use that endpoint on an existing domain.

Send exact names, or a seed to generate variations from a brand. Reserves nothing and charges nothing, but it does hit the registrar on our account, which is why it costs a request against the rate limit rather than being open.

price_cents is what a purchase will actually take off the balance — registrar cost plus markup, rounded up to the next whole dollar plus another dollar (whole-dollar prices, same as Winnr). registrar_cents is the wholesale figure before markup and rounding.

The dns block is the useful part. expected is the record we asked the DNS provider to create; observed is what a public resolver actually returns. They are stored separately on purpose, because conflating them produces a dashboard that says "configured" while mail quietly fails authentication.

pending_nameservers is populated on a connected domain that has not been delegated yet, and is what to show the customer. It is always null on the manual and cloudflare_token methods, because there is no zone of ours to delegate to — on those, the dns block is the whole story.

On a manual domain this endpoint is the work order: every record with a status other than verified is one somebody still has to add or correct at your DNS host. expected is complete and unabridged so it can be pasted character for character.

An action name rather than a verb per operation. Releasing is not a delete — the registration outlives it — and re-checking DNS mutates nothing, so a REST-shaped mapping would have described these worse than this does.

All four are queued rather than run inline. Re-checking DNS means resolving against several public resolvers, which is slow and fails in ways that need retrying; doing it in the request would mean a spinner that sometimes just gives up.

The third connect method, and the one worth preferring if the zone is already at Cloudflare. The zone stays yours; we write and maintain the mail records inside it with a token you scope yourself. Nothing is delegated, and unlike manual you are not the one who has to keep up with a DKIM rotation.

Its own endpoint rather than a field on the create call, because a token has to be proved against the zone before it is worth storing — accepting it at create time would mean either keeping an unproven credential or failing a batch of forty domains on one bad paste.

The only synchronous action on a domain. Everything else queues a job, but the reason to check a token at all is to say now that its scope is wrong, while the caller still has it in hand.

warming.campaign_ready is the field to gate a campaign on, and warming.campaign_blocker says what is missing when it is false. The warming day alone is not enough: a mailbox at its ceiling with 60% placement is worse to send from than one halfway up the curve at 98%.

Two ways to say what you want. Send personas when the names matter — real-looking first and last names are part of why warming works — or send count and let us generate plausible ones against the domain’s local-part pattern.

The addresses are recorded immediately and provisioned by a job, so the response has the addresses in it before the mail server has them. overageBillable is true when the batch takes the account past its included allowance; those mailboxes are billed rather than refused.

Around five mailboxes to a domain is the balance point, and varying the number between domains is worth doing: a fleet holding precisely five addresses on every domain is a fact about the tool that built it. Spreading volume over more domains beats pushing harder on fewer.

Everything the list returns plus the signature, placement rates, sync timestamps and — when provisioning failed — the reason. failure_reason is returned rather than hidden because a status: "failed" with no explanation is the single most common thing a customer opens a ticket about.

Does not include the password. Credentials come from the export endpoint, which needs admin and is audited.

Fields rather than an action name, because these are settings and a client that wants to pause a mailbox and drop its limit should not need two requests that can half-fail.

warming: false and warming_paused: true are different things and the difference is money. Disabling stops the warming charge. Pausing stops the sending, keeps the mailbox’s place on the ramp, and keeps billing. Sending both is rejected rather than guessed at.

Irreversible, and it discards the warming history — a replacement address starts from zero and has to earn its placement evidence again. Pausing is almost always the better answer if the goal is only to stop sending.

Returns text/csv, not JSON. Contains plaintext passwords, which is why it needs admin on its own rather than inheriting from write, and why every call is written to the audit log.

Only mailboxes that have finished provisioning and are warming, active or paused are included. The count is returned in the X-EmailPal-Exported header, and anything skipped for unreadable credentials in X-EmailPal-Skipped.

The question this answers is whether to start a campaign. campaign_ready is our answer to the combined question and campaign_blocker says what is missing when it is false, so a client does not have to reimplement the rule from the parts.

Behind it: inbox_rate below 85% means the domain is not trusted yet whatever day the ramp says it is on, ramp_progress is how far today’s volume has climbed toward the ceiling rather than how much time has passed, and rescued_from_spam above zero is an early warning even while the inbox rate still looks acceptable.

target is messages, not conversations: a warming conversation is answered and the answer is answered, so a mailbox spends a little over two messages on each one it starts. That is why conversations_started sits well below sent on every row and is not a shortfall.

Read from a daily rollup rather than counting messages, so polling this is cheap.

Up to five hundred mailboxes in one call. Here rather than as a loop over PATCH /mailboxes/{id} because switching warming on for a hundred new addresses is one decision, and a client making a hundred calls to express it will hit the rate limit doing so and then have a hundred partial outcomes to reconcile.

Four verbs, not a boolean, because disable stops the charge and pause does not. A paused mailbox keeps its place on the ramp and stays billed; the response repeats this in billing.note so a confirmation dialog can quote it.

Mailboxes that could not be changed come back in skipped with a reason each, rather than failing the whole call.

enable is refused outright, before anything changes, on an account with no active subscription that is not complimentary — see subscription_required below. disable, pause and resume are never blocked this way.

Newest first, across every mailbox, with a preview. Warming traffic is excluded unless you ask for it: it is the majority of what arrives and none of it is from a real prospect.

Bodies are not included. Fetching one means talking to the mail server, so it is a separate call.

Returns 202 with status: "fetching" when the body is not cached, because getting it means an IMAP round trip we will not hold a connection open for. Poll this same URL — not /jobs/{id} — until status is ready. It is usually a second or two.

The headers and preview are present in both cases, so a client can render the message frame immediately and fill the body in when it arrives.

Send at least one of the two. The change is written locally and pushed to the mail server on the next sync.

Queued, because it has to reach the mail server. The message disappears from listings immediately.

Sends as the named mailbox. Pass reply_to_id to thread the message properly — we derive the In-Reply-To and References headers from the original, which is what stops a reply arriving as a new conversation.

Recipients are checked against the suppression list before the message is queued. A suppressed address is a 409 rather than a silent drop, because a client that thinks it sent something it did not is worse off than one that got an error.

If you are answering a message we never saw — one your sequencer sent over SMTP, for instance — pass in_reply_to and references instead. Send one or the other, not both: where we can derive the headers ourselves we do, because a derived thread cannot be pointed at a conversation the account does not own.

Accepts an Idempotency-Key header. The RFC Message-ID appears on the job result once the send completes, and the receiver’s verdict on it at GET /inbox/send/{id}.

The job behind a send finishes when our MTA accepts the message, so a succeeded job means we handed it over and nothing more. What the receiving server decided arrives minutes to hours later, and shows up here.

status is our side of the send; delivery_status is theirs. A hard bounce also adds the address to the suppression list, so no account sends to it again.

Subscribe to message.delivery_updated rather than polling this. The verdict has no schedule, so polling means either asking too often or learning too late.

Mail syncs on its own schedule; this is for when you need it sooner. Rate limited to one sync per mailbox per thirty seconds, so calling it in a loop is harmless and also pointless — the extra calls come back with queued: 0.

Omit mailbox_id to sync every eligible mailbox on the account, up to two hundred.

Counts and price bands, never names. Publishing the exact names of unsold stock invites somebody to register the good ones out from under us, so this answers how many, how old and how much — and the names appear on GET /domains once they are yours.

previously_used is the part of the shelf recovered from accounts that left, re-warmed and re-listed once it cleared the health bar. First-hand stock is handed out first, so that price only applies once the clean shelf is empty.

Takes domains off the shelf and attaches them to your account, charged against the domain balance. Which domains you get is decided in the worker under a row lock, because the price depends on the age of the specific domain assigned and two callers claiming at the same moment must not be promised the same one.

Returns a job. Poll it: DNS is re-checked and the parking page comes down before a domain is marked ready.

An aged domain stops you looking brand new; it does not give you an address a receiver has already seen behaving well. These are those addresses — provisioned onto inventory domains months before anyone asks and warmed continuously since, which is why they are leased monthly rather than sold. The warming is the product.

This is the endpoint to build an overflow pool on: a tenant who needs to send this week cannot wait out a fourteen-day ramp.

Counts and a health band, never addresses. previously_leased is disclosed here rather than at the point of sale, because finding out afterwards that an address had a previous tenant is being misled even when the reputation is genuinely the address’s own.

Leases warmed addresses onto your account. They arrive campaign-ready rather than at day zero of a ramp, keep warming inside the monthly rate, and have their passwords rotated on handover so nothing we used to run the warming still opens them.

A minimum term applies, and it is enforced on delete as well as here — a term a script can walk around by calling the API instead of clicking the button is not a term.

Newest first. Filter by type to watch one kind of work, or by status to find what failed.

The poll target for everything asynchronous. terminal is the field to loop on — it is true for succeeded, failed, dead and cancelled, so a client does not have to keep its own list of which statuses mean stop.

retry_after is set when a job failed but has attempts left, and is the time the queue will try again on its own. A dead job has run out of attempts and will not.

Retry puts a failed, dead or cancelled job back on the queue with its attempt count reset. Cancel stops one that has not finished.

Retrying is safe: every job that touches money or a registrar carries an idempotency key, so a retried purchase cannot buy the same domain twice.

Every endpoint on the account, with its recent health. Secrets are never included — they are shown once, when the endpoint is created or its secret is rotated.

available_events lists every event we can send, so a subscription UI can be built from the API rather than from a docs page somebody has to remember to update.

Returns the signing secret once. Store it before you close the response — no later read gives it back, and the only way to recover is to rotate.

Every delivery carries an EmailPal-Signature header:

`` EmailPal-Signature: t=1774483200,v1=5257a869e7... ``

Verify it by computing HMAC-SHA256 over ${t}.${raw_body} with your secret and comparing the hex digest to v1, in constant time. Reject anything whose t is more than five minutes from your clock — the timestamp is inside the MAC precisely so a captured payload cannot be replayed later.

Compare against the raw body, before any JSON parsing. Re-serialising changes the bytes and the signature will not match.

Delivery is at-least-once. Dedupe on the id field, which is stable across retries.

The last twenty delivery attempts, with the status code and error text your endpoint returned. This is the endpoint to open when something did not arrive — the answer is nearly always in the attempts rather than in the configuration.

Setting enabled: true on an endpoint we disabled automatically also clears its failure count — otherwise the first hiccup after a fix would switch it straight back off.

rotate_secret issues a new secret and returns it once. The old one stops working immediately: a leaked secret is not made safer by a grace period during which it still verifies.

Queued deliveries go with it. Keeping them would leave an outbox with nowhere to send to, retried until it died.

Two modes. Pass address to ask about one address and get a direct yes or no — that is the call to make before a send, and it answers for domain-level suppressions too, which a naive lookup against your own copy of the list would miss.

Omit it to page through everything suppressed on the account.

Exactly one of address or domain. Suppressing a domain stops mail to every address on it, which is the right response to an abuse complaint from a company rather than a person.

Suppressing something already suppressed returns 200 rather than an error, so an integration that replays its own queue does not have to special-case it.

Send the raw file contents — CSV, one-per-line, or anything with addresses in it — and we extract the addresses and check every one of them. A list that would mostly bounce is worth knowing about before it costs you a domain rather than after.

This is the same engine as POST /verify, run over a whole file, and it returns the same status vocabulary — including catch_all, inbox_full and disabled, which need a live check of the mailbox and cannot be inferred from a domain’s records.

Costs one verification credit per extracted address, taken in full when the list is accepted. A list that does not fit in what is left of today’s allowance is refused outright rather than half-answered, and the error names the shortfall so you can split the file.

Asynchronous, and results arrive as they are decided rather than all at the end. Two poll targets, both usable while the list is still running: GET /lists/{id}/results for the per-address answers, and GET /lists/{id} for the counts and the whole-list verdict. Neither is the job — everything worth reading lives on the upload.

The addresses themselves, one row each, in the order they were answered. Readable while the list is still running — that is the point of it. A list larger than the verification capacity free right now is answered over hours, and waiting for status to leave verifying would mean sitting on nothing while thousands of usable answers piled up behind it.

Paged oldest-first, unlike the other list endpoints. Keep the next_cursor from your last response and every poll returns only what has been decided since, so draining a list of any size costs one pass over it.

has_more: false means you are caught up with what has been decided, not that the list is done. Branch on list.finished for that, and keep polling with the same cursor until it is true.

Poll until status leaves pending and verifying. sendable is the field to branch on: it is true for passed and flagged, and false for blocked and failed.

flagged means send it but know what is in it. blocked means the list would damage the reputation of every domain on the account, and blocked_reason says which measure crossed the line.

Every count except risky is one status per address, in the same vocabulary POST /verify uses, and risky is the derived figure the block threshold is applied to: catch_all + role_account + disposable.

The counts fill in as the list is checked, so they are worth reading before it finishes — but while status is verifying they describe only the addresses answered so far and will sum to less than total. progress.remaining is the gap. They sum to total once it is done.

For the addresses rather than the totals, use GET /lists/{id}/results.

Instant, not queued — this is the one exception to the async-for-anything-that-touches-mail rule, because the reason to call it is to decide something before the next line of code runs, the same way you would call Reoon or NeverBounce.

Metered out of the same daily allowance as POST /lists/verify, at the same one-credit-per-address rate, because it is the same probe against the same egress pool. The plan includes an allowance and more is bought in blocks of 500/day from the dashboard's Email Verification card. credits.limit and credits.used in the response are that allowance, checked and incremented before the address is ever probed — a failed probe still spends the credit, the same rule the hourly rate limit uses, because a client retrying a slow domain for free is the case metering exists for. The one exception is a 503: if we had no egress address free to probe from, nothing was attempted and the credit goes back.

The verdict vocabulary is the one Reoon and NeverBounce use, so switching over is a find-and-replace: safe, invalid, disposable, role_account, catch_all, disabled, inbox_full or unknown. sub_status narrows unknown and invalid further — no_mx_record, unable_to_connect and antispam_system (greylisted; we do not retry inline) are the ones worth branching on, since each suggests a different next step.