Reference
Every endpoint the API serves — 103 of them — with what each one needs and the exact body it accepts. Generated from the running server, so it describes the API you are calling rather than the one somebody remembered to document.
https://api.posthastemail.dev. The machine-readable document is at /v1/openapi.json, and there is a Postman collection whose example bodies are tested against the same schemas the server validates with./v1/accountdashboard session onlyRequires a signed-in person with the **admin** role or higher — rename the account. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
| Field | Type | Notes |
|---|---|---|
| name | string required |
/v1/account/deletiondashboard session onlyRequires a signed-in session, acting on your own record — see whether a deletion is scheduled. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/account/deletiondashboard session onlyRight to erasure. Scheduled rather than immediate, so it can be cancelled.
Requires a signed-in person with the **owner** role or higher — delete the account. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/account/deletiondashboard session onlyRequires a signed-in person with the **owner** role or higher — cancel a scheduled deletion. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/account/verifyaccount:readThe same verdict as `/v1/audit/verify`, in the older, narrower shape: `intact`, `brokenAt`, `problem`. Reachable with `account:read` because it returns no part of the log itself.
Requires an API key with `account:read`, or a signed-in session.
/v1/meaccount:readRequires an API key with `account:read`, or a signed-in session.
/v1/profiledashboard session onlyRequires a signed-in session, acting on your own record — set your own name. Deliberately not role-gated, because the row being changed is the caller’s own.
| Field | Type | Notes |
|---|---|---|
| name | string required |
/v1/usageaccount:readRequires an API key with `account:read`, or a signed-in session.
/v1/alerts/eventsalerts:readNewest first, keyset-paginated. Each row carries the value and the threshold AS THEY STOOD, not as they are now, plus which channels the notice was delivered on — so "you never told us" has an answer that survives somebody editing the rule afterwards.
Requires an API key with `alerts:read`, or a signed-in session.
/v1/alerts/rulesalerts:readEvery threshold on the account, with the live firing state and the last measurement. Also returns the vocabulary — the available kinds, their units and their defaults — so a client never has to hard-code them.
Requires an API key with `alerts:read`, or a signed-in session.
/v1/alerts/rulesalerts:writeWith a body, creates one rule. With NO body, creates the default set for every kind — which is the "switch alerting on" call, because picking four thresholds before you have ever seen one fire is guesswork.
One rule per kind: a second one answers 409. Two rules watching one signal would mean two emails about it, which is the failure alerting exists to avoid.
`threshold` is a fraction for the rate kinds (`0.003` is 0.3%) and a count for `dns_drift`. It is refused above the point at which the account would be suspended for the same numbers, since an alert that can only arrive after the suspension is not an alert.
Requires an API key with `alerts:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| kind | "complaint_rate" | "bounce_rate" | "quota_usage" | "dns_drift" required | |
| threshold | number required | |
| windowDays | integer optional | |
| cooldownMinutes | integer optional | |
| notifyEmail | boolean optional | |
| notifyWebhook | boolean optional | |
| enabled | boolean optional |
/v1/alerts/rules/{id}alerts:writeEditing a rule never re-arms it. An alert that is currently firing stays firing, and raising the threshold while it is open is not a way to be told about it a second time.
Requires an API key with `alerts:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| threshold | number optional | |
| windowDays | integer optional | |
| cooldownMinutes | integer optional | |
| notifyEmail | boolean optional | |
| notifyWebhook | boolean optional | |
| enabled | boolean optional |
/v1/alerts/rules/{id}alerts:writeRequires an API key with `alerts:write`, or a signed-in session.
/v1/api-keysaccount:readRequires an API key with `account:read`, or a signed-in session.
/v1/api-keysdashboard session onlyThe secret is returned once and never again.
Requires a signed-in person with the **admin** role or higher — mint an API key. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
| Field | Type | Notes |
|---|---|---|
| name | string required | |
| scopes | string[] required |
/v1/api-keys/{id}dashboard session onlyRequires a signed-in person with the **admin** role or higher — revoke an API key. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/audit/eventsmessages:readThe append-only, hash-chained record of everything that has happened to this account’s mail, newest first. Each entry carries its own `hash` and `prevHash`, so a single row can be checked without downloading the whole log.
Deliberately does NOT verify the chain: verification replays the entire history, and doing that per page would make paging cost more the longer you have been a customer. Use `/v1/audit/verify` for the verdict.
Requires an API key with `messages:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| limit | integer optional | |
| before | integer optional | |
| type | string optional | |
| from | string optional | |
| until | string optional |
/v1/audit/exportmessages:readStreams the whole chain as newline-delimited JSON, oldest first, with a header record describing how the hash is constructed and a trailer record carrying the event count and the verdict.
`payload` is the exact text the database hashed and `occurredAt` the exact timestamp string. Hash them as given — re-serialising the parsed JSON changes the bytes and fails verification on an untouched record.
A file with no trailer record is INCOMPLETE. The response status is sent before the last row is read, so a failure mid-transfer can only truncate the download; the trailer is how you tell a whole export from half of one.
Requires an API key with `messages:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| from | string optional | |
| until | string optional |
/v1/audit/verifymessages:readReplays every event on the account, in order, and reports the first break by sequence number. Answers 200 whether or not the record holds — a broken chain is evidence, not a server fault, and returning 5xx would make it look like a transient error worth retrying.
`purgedThroughSeq` is non-zero when the oldest events have aged out of your plan’s retention window through the audited purge path. That is why a chain may legitimately start above 1.
Requires an API key with `messages:read`, or a signed-in session.
/v1/auth/2fa/disabledashboard session onlyRequires a signed-in session, acting on your own record — remove your own authenticator. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/2fa/enabledashboard session onlyRequires a signed-in session, acting on your own record — enrol your own authenticator. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/2fa/setupdashboard session onlyRequires a signed-in session, acting on your own record — enrol your own authenticator. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/google/callbackNo authentication: is how a session is obtained.
/v1/auth/google/nonceNo authentication: is how a session is obtained.
/v1/auth/google/one-tapNo authentication: is how a session is obtained.
/v1/auth/google/startNo authentication: is how a session is obtained.
/v1/auth/loginNo authentication: is how a session is obtained.
| Field | Type | Notes |
|---|---|---|
| string required | ||
| password | string required | |
| code | string optional |
/v1/auth/logoutNo authentication: must work even with a dead session.
/v1/auth/meHow the dashboard learns its auth state on boot; no token is readable from JavaScript.
No authentication: answers "am I signed in" for the dashboard on boot.
/v1/auth/passkeysdashboard session onlyRequires a signed-in session, acting on your own record — list your own passkeys. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/passkeys/{id}dashboard session onlyRequires a signed-in session, acting on your own record — remove your own passkey. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/passkeys/login/optionsNo authentication: is how a session is obtained.
/v1/auth/passkeys/login/verifyNo authentication: is how a session is obtained.
/v1/auth/passkeys/register/optionsdashboard session onlyRequires a signed-in session, acting on your own record — add your own passkey. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/passkeys/register/verifydashboard session onlyRequires a signed-in session, acting on your own record — add your own passkey. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/password/changedashboard session onlyRequires a signed-in session, acting on your own record — change your own password. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/password/forgotAnswers the same way whether or not the address is known, so it cannot be used to test which addresses exist.
No authentication: is reached by somebody who has by definition failed to sign in.
/v1/auth/password/resetNo header credential. A single-use token in the request body IS the credential, and it is reached from a mailbox.
/v1/auth/sessionsdashboard session onlyRequires a signed-in session, acting on your own record — list your own sessions. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/sessions/revoke-othersdashboard session onlyRequires a signed-in session, acting on your own record — sign your other devices out. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/auth/signupNo authentication: creates the first account.
| Field | Type | Notes |
|---|---|---|
| string required | ||
| password | string required | |
| accountName | string optional |
/v1/auth/verify-emailNo header credential. A single-use token in the request body IS the credential, and it is reached from a mailbox.
/v1/auth/verify-email/senddashboard session onlyRequires a signed-in session, acting on your own record — resend your own confirmation. Deliberately not role-gated, because the row being changed is the caller’s own.
/v1/billingbilling:read or account:readRequires an API key with `billing:read` or `account:read`, or a signed-in session.
/v1/billing/{provider}/webhookAuthenticated by the provider signature over the RAW body, so it cannot be re-signed from a parsed copy.
No header credential. The caller is a payment or mail provider and is authenticated by its signature over the RAW request body — so this operation cannot be re-signed from a parsed copy.
/v1/billing/canceldashboard session onlyRequires a signed-in person with the **admin** role or higher — cancel the plan. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/billing/checkoutdashboard session onlyRequires a signed-in person with the **admin** role or higher — start a checkout. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
| Field | Type | Notes |
|---|---|---|
| plan | string required | |
| interval | "month" | "year" optional | |
| profile | object required |
/v1/billing/checkout/abandondashboard session onlyRequires a signed-in person with the **admin** role or higher — abandon a checkout. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/billing/historybilling:read or account:readRequires an API key with `billing:read` or `account:read`, or a signed-in session.
/v1/billing/invoicesbilling:read or account:readRequires an API key with `billing:read` or `account:read` (checked via `canReadBilling`), or a signed-in session.
/v1/billing/invoices/{id}billing:read or account:readRequires an API key with `billing:read` or `account:read` (checked via `canReadBilling`), or a signed-in session.
/v1/billing/pausedashboard session onlyRequires a signed-in person with the **admin** role or higher — pause the plan. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/billing/profiledashboard session onlyRequires a signed-in person with the **admin** role or higher — change the billing details. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/billing/resumedashboard session onlyRequires a signed-in person with the **admin** role or higher — resume the plan. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/analytics/deliveryanalytics:readAnswers "is Outlook slower than Gmail for our mail". Returns the delivery rate and the p50/p95 time to inbox for each receiving domain, or for each of your own tags, over a window you choose.
Time to inbox is measured between two events on the message: `accepted`, when it entered the delivery queue, and `delivered`, when the receiving mail server accepted it. It does not include what that server does afterwards, which no sender can observe.
A rate with nothing settled behind it and a percentile with no delivered message behind it are both `null`, never `0`. Every row carries the number of messages its percentiles were computed from.
Requires an API key with `analytics:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| days | integer optional | |
| groupBy | string optional | |
| stream | string optional | |
| tag | string optional | |
| limit | integer optional | |
| cursor | string optional |
/v1/analytics/dmarcanalytics:readSummarises the DMARC aggregate reports receiving providers send back about your domains, grouped by the IP that sent the mail and ranked by volume.
`messages` is the volume the reporters accounted for, summed from each report row's own count — not a number of rows, since a single row can stand for millions of messages. A message counts as aligned when SPF **or** DKIM aligned with the From domain, which is what DMARC itself requires; a mechanism that passed for some unrelated domain does not count.
A source with volume and no alignment is either a legitimate sender you have forgotten about or somebody spoofing you. The two are indistinguishable from here, so this reports what the receivers observed and leaves that judgement to you.
`alignmentRate` is `null` rather than `0` when no reports have arrived yet, because "nothing reported" and "everything failed" are opposite situations.
Requires an API key with `analytics:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| days | integer optional | |
| domain | string optional |
/v1/account/cloudflaredomains:writeRequires an API key with `domains:write`, or a signed-in session.
/v1/domainsdomains:readRequires an API key with `domains:read`, or a signed-in session.
/v1/domainsdomains:writeReturns the DNS records to publish. Mail cannot be sent until it verifies.
Requires an API key with `domains:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| name | string required |
/v1/domains/{id}domains:writeRequires an API key with `domains:write`, or a signed-in session.
/v1/domains/{id}/cloudflaredomains:writeRequires an API key with `domains:write`, or a signed-in session.
/v1/domains/{id}/setupdomains:readRequires an API key with `domains:read`, or a signed-in session.
/v1/domains/{id}/verifydomains:writeRequires an API key with `domains:write`, or a signed-in session.
/v1/emailsemails:sendAccepts a message, stores it durably, and queues it for delivery. Returns 202 with the message id — acceptance is not delivery, and the delivery outcome arrives on the webhook or in the message log.
Supply `html`/`text`, or a `template` with `variables`. A missing required template variable is a refusal, not a blank: rendering fails and nothing is sent.
Requires an API key with `emails:send`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| from | string required | |
| to | string | string[] required | |
| cc | string[] optional | |
| bcc | string[] optional | |
| subject | string optional | |
| text | string optional | |
| html | string optional | |
| replyTo | string optional | |
| headers | object optional | |
| listUnsubscribe | string optional | |
| stream | string optional | |
| template | string optional | |
| templateVersion | integer optional | |
| variables | object optional | |
| tags | string[] optional | |
| metadata | object optional | |
| idempotencyKey | string optional | |
| scheduledAt | string optional | |
| attachments | object[] optional |
/v1/emails/{id}/scheduleemails:sendRequires an API key with `emails:send`, or a signed-in session.
/v1/emails/batchemails:sendPartial success is the contract: each item succeeds or fails on its own and one bad recipient never fails the batch. Each item commits independently, so an accepted message stays accepted whatever happens to the rest.
Requires an API key with `emails:send`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| messages | object[] required |
/v1/inbound/addressesdomains:readRequires an API key with `domains:read`, or a signed-in session.
/v1/inbound/addressesdomains:writeRequires an API key with `domains:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| address | string required | |
| label | string optional |
/v1/inbound/addresses/{id}domains:writeRequires an API key with `domains:write`, or a signed-in session.
/v1/inbound/messagesmessages:readRequires an API key with `messages:read`, or a signed-in session.
/v1/inbound/messages/{id}messages:readHTML is sanitised on the way out, without exception.
Requires an API key with `messages:read`, or a signed-in session.
/v1/inbound/messages/{id}domains:writeRequires an API key with `domains:write`, or a signed-in session.
/v1/messagesmessages:readFilterable by status, tag, stream, recipient domain, metadata and date. Repeated `tag` parameters are ANDed.
Requires an API key with `messages:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| limit | integer optional | |
| before | string optional | |
| status | string optional | |
| to | string optional | |
| search | string optional | |
| domain | string optional | |
| stream | string optional | |
| tag | string optional | |
| metadata | string optional | |
| from | string optional | |
| until | string optional |
/v1/messages/{id}messages:readRequires an API key with `messages:read`, or a signed-in session.
/v1/messages/{id}/attachments/{attachmentId}messages:readServed `Content-Disposition: attachment` — never rendered inline on our origin, whatever the declared content type.
Requires an API key with `messages:read`, or a signed-in session.
/v1/messages/tailmessages:readA Server-Sent Events stream of the same events the message log holds, delivered as they are written. Nothing polls: the connection is idle until an event lands.
Each `message` event carries the account `seq` as its SSE id. Reconnect with `Last-Event-ID` (browsers send it automatically) or `?after=<seq>` and everything after that position is replayed, so a dropped connection loses nothing.
A `ready` event opens the stream, `heartbeat` arrives every 15 seconds, and `bye` says why we closed. The stream is closed after 15 minutes with no message event; reconnect and resume. Five concurrent tails per account — a sixth is refused with `too_many_streams`.
Requires an API key with `messages:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| status | string optional | |
| stream | string optional | |
| tag | string optional | |
| replay | integer optional | |
| after | integer optional |
/v1/stats/messagesmessages:readRequires an API key with `messages:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| days | integer optional | |
| domain | string optional | |
| tz | string optional |
/v1/leadsRequires the platform account's own key: the marketing contact form.
/v1/openapi.jsonServed from the running server, so it always describes the API you are calling.
No authentication: describes only the public API, which is equally discoverable by trying it.
/v1/streamsstreams:readRequires an API key with `streams:read`, or a signed-in session.
/v1/streamsstreams:writeStreams separate suppression scope and statistics, so a complaint on one stream can never suppress a password reset on another.
Requires an API key with `streams:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| slug | string required | |
| name | string required |
/v1/sub-accountsaccount:readReturns what a payer is entitled to know — name, status and volume this month. Never the sub-account’s mail, domains or suppressions: the billing relationship is not a window into its data.
Requires an API key with `account:read`, or a signed-in session.
/v1/sub-accountsdashboard session onlyA fully isolated account with its own domains, keys and suppression list, billed to you and sharing your monthly allowance. It inherits your plan and cannot hold a subscription of its own.
Requires a signed-in person with the **admin** role or higher — add an account to the bill. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
| Field | Type | Notes |
|---|---|---|
| name | string required |
/v1/sub-accounts/{id}account:readRequires an API key with `account:read`, or a signed-in session.
/v1/suppressionssuppressions:readEvery entry carries its cause: the reason, the receiving server’s own words, its status code, and the message whose bounce or complaint caused it. An entry added by hand has no causing message, and neither has one whose message has since aged out of retention.
Requires an API key with `suppressions:read`, or a signed-in session.
| Parameter | Type | Notes |
|---|---|---|
| limit | integer optional | |
| before | string optional | |
| search | string optional | |
| reason | string optional |
/v1/suppressionssuppressions:writeRequires an API key with `suppressions:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| address | string required | |
| reason | string optional | |
| stream | string optional |
/v1/suppressions/{address}suppressions:writeRemoves a `manual` or `unsubscribe` entry. A hard bounce cannot be removed this way (422 suppression_hard_bounce): re-sending to an address that does not exist is what costs a sender its reputation, and a genuinely stale one is lifted by support after review. A complaint or spam trap can never be removed at all (422 suppression_protected).
Requires an API key with `suppressions:write`, or a signed-in session.
/v1/teamteam:readRequires an API key with `team:read`, or a signed-in session.
/v1/team/{id}dashboard session onlyThe person is signed out everywhere, because their permissions changed.
Requires a signed-in person with the **admin** role or higher — change a colleague's role. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
| Field | Type | Notes |
|---|---|---|
| role | "owner" | "admin" | "member" | "viewer" required |
/v1/team/{id}dashboard session onlyThe last owner cannot be removed — an account with no owner has nobody who can administer it.
Requires a signed-in person with the **admin** role or higher — remove a colleague. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
/v1/team/invitesdashboard session onlyRequires a signed-in person with the **admin** role or higher — invite a colleague. NOT reachable with an API key: this is an action where a leaked server-side credential would be catastrophic.
| Field | Type | Notes |
|---|---|---|
| string required | ||
| role | "owner" | "admin" | "member" | "viewer" required |
/v1/team/invites/acceptSets the password and verifies the address. Does not sign you in.
No header credential. A single-use token in the request body IS the credential, and it is reached from a mailbox.
| Field | Type | Notes |
|---|---|---|
| token | string required | |
| password | string required |
/v1/templatestemplates:readRequires an API key with `templates:read`, or a signed-in session.
/v1/templatestemplates:writeRequires an API key with `templates:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| subject | string optional | |
| html | string optional | |
| text | string optional | |
| variables | object[] optional |
/v1/templates/{id}templates:readRequires an API key with `templates:read`, or a signed-in session.
/v1/templates/{id}templates:writeA published version is immutable. Editing content publishes the next version and leaves the previous one byte-identical, so a send can always be traced to the exact content that went out.
Requires an API key with `templates:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| subject | string optional | |
| html | string optional | |
| text | string optional | |
| variables | object[] optional |
/v1/templates/{id}templates:writeRequires an API key with `templates:write`, or a signed-in session.
/v1/templates/{id}/previewtemplates:readReturns the rendered HTML and text for sample variables, and reports the same refusals a send would — so a preview cannot pass where the send fails.
Requires an API key with `templates:read`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| version | integer optional | |
| variables | object optional |
/v1/templates/{id}/versionstemplates:readRequires an API key with `templates:read`, or a signed-in session.
/v1/templates/previewtemplates:readRenders what you supply rather than what you have published, so an editor can show a template before it exists. Reports the same refusals and the same lint a send would, and stores nothing.
Requires an API key with `templates:read`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| subject | string optional | |
| html | string optional | |
| text | string optional | |
| variables | object[] optional | |
| values | object optional |
/v1/webhookswebhooks:readRequires an API key with `webhooks:read`, or a signed-in session.
/v1/webhookswebhooks:writeDeliveries are signed; verify the signature before trusting a payload. Retried with backoff and idempotent on redelivery.
Requires an API key with `webhooks:write`, or a signed-in session.
| Field | Type | Notes |
|---|---|---|
| url | string required | |
| eventTypes | string[] optional |
/v1/webhooks/{id}webhooks:writeRequires an API key with `webhooks:write`, or a signed-in session.
NextErrors →Every error type the API returns, what causes it, and whether to retry.