API reference

Describe the key itself: label, premium scope, allowlist, budget, and usage counters.

Address quota, message totals, retention, and the key profile in one call.

Everything a client needs to self-throttle: scopes, request counters for 24h and 7d, the twenty busiest endpoints with their error counts, address quota, message counters, and the effective retention window.

Machine-readable capabilities document: api version, operation count per group, the full error-code list, request and response headers, pagination style, and the webhook event catalogue. Useful for client bootstrapping without fetching openapi.json.

Introspect the presented key: scopes, premium flag, budgets, quotas, effective retention, status, and the lifetime request counter. Read-only by design, keys are provisioned from the panel.

Roll the presented key: a fresh secret is generated, the old one stops working on the next request. Shown once, in full, in this response only.

The plan the key resolves to, the hard limits that plan enforces, and the whole assignable catalog so a client can render an upgrade path without guessing.

Per-request audit trail for this key: method, path, status, outcome, IP, and the request id you also receive in the x-request-id header. Filter it to isolate every denied or throttled call.

List every address this key owns, newest first, with the quota snapshot in meta.

Create an address. Omit local_part for a random one, or choose its shape with local_part_type. Domain must be active with mail enabled.

One address, its alias group, and its newest messages. Accepts the public id or the full email address.

The mailbox subresource: every message on one address, with the full /inbox filter grammar still available. Use it when the address is the scope and you do not want to repeat the address on every call.

Soft-delete the address and hide its messages from the inbox. purge_after is stamped so the row survives the five minute grace window before the hard delete.

Relabel, disable, re-enable, extend the lifetime, or rotate the password of an address without changing the address string. Extending ttl_minutes also moves purge_after.

Newest messages first. Filter by address, sender, subject, To recipient, sender display name, exact Message-ID, header Date window, size range, priority, attachments, spam state, unread, or poll with since_id.

Bulk mark messages as read. Every inbox filter is honoured, plus an optional ids array to target specific messages. Send no body to act on the whole filtered scope. Returns the affected row count and the refreshed counters.

Bulk mark messages as unread. Identical contract to /inbox/read: same filters, same optional ids array, same response shape.

Counter snapshot for the whole filtered scope: total, unread, read, deleted, attachments, starred. Accepts every inbox filter, so you can scope it per address.

Mark messages as starred. Same body and filter contract as /inbox/read: optional ids array, otherwise the whole filtered scope.

Remove the star flag from messages. Identical contract to /inbox/star.

Bulk soft delete every message matching the filters or the supplied ids, up to 5000 rows in one call. message_count is recalculated for each touched address.

Undo a soft delete. Restores the messages into the inbox and refreshes the per-address message_count.

Flat attachment index across every message this key can read, newest first. One page of messages in, every attachment on those messages out, each with checksum_sha256 and a ready-to-call download_path pointing at /messages/{id}/attachment/{attachmentId}.

The full message: envelope-level sender and recipient, header Date with a validity flag, In-Reply-To, References, priority, Received chain, DKIM signatures, Authentication-Results (joined into one string), attachment checksums, raw_available, and the decoded text and html bodies. Marks it read. Password-protected addresses require the password query param.

Update the read flag or restore a soft-deleted message. Send seen and/or is_deleted; send neither and the call is rejected with 422.

Download the stored message as raw RFC 822 bytes (message/rfc822, attachment disposition).

Fetch one attachment by its SHA-256 checksum (full or prefix), its zero-based index, or its att_N label. Content-type and filename come from the MIME part.

Soft-delete one message.

One call for the whole sweep: delete, read, unread, star or unstar every message that matches an address, a filter, or an explicit id list. Caps at 500 rows per call on purpose so a runaway sweep cannot take the mailbox with it.

Full-text search across subject and body for the mail this key owns. Same filter grammar as /inbox, prefix q with +term to require a word and -term to exclude it, quote a phrase to match it literally.

Two views in one route: with no key ownership rows this lists the public catalog; domains this key registered always appear here too. Filters cover status, type, and mail routing state.

Fetch one domain by public id or by name. One call, no list scan.

Ask whether a domain is registerable before the user commits to it.

Register a custom domain for temp mail. Returns the TXT challenge to publish before verifying.

Update notes, toggle mail routing, or set mail_cap_hours. mail_enabled only flips while the domain is active.

Soft-delete your domain and pull it from the MX routing table instantly.

Run the TXT + MX check and flip pending_verification to verified on success.

Issue a fresh 72h TXT challenge token; resets verification state.

Live DNS probe without state changes; writes last_check_result for the detail view.

Lifecycle moves plus moderation: activate, resume, block for spam, fraud, abuse, or phishing, and lift the block.

Per-domain counters for this key only: how many addresses live on each routable domain and how many live messages it holds. Answers "which of my domains is actually carrying traffic" without paging the inbox.

List the webhooks registered for this key, newest first. The signing secret is returned once at creation and afterwards only as a stored value on this endpoint.

Register a webhook. Ten active hooks per key. Honours the idempotency-key header so a retried POST does not double-register.

One webhook plus its recent delivery log: event, HTTP status, duration, attempts, error. Use it to debug a receiver that started refusing payloads.

Change the target URL, description, event list, or flip active on and off. Pausing keeps the delivery log.

Delete the webhook and its delivery log. Irreversible; pause with PATCH active=false when the receiver is only temporarily broken.

Send a signed webhook.test delivery right now and get the receiver status back synchronously. The fastest way to prove the signature check on your end before a real mail arrives.

The inbound allow and block list for this key, with counts per kind. Rules are evaluated before a message is stored, so a blocked sender never lands in the mailbox at all.

Add a rule, or flip the kind on an existing pattern. Once a key carries at least one allow rule the list becomes a real allowlist: any sender that matches nothing is treated as blocked.

One rule by numeric id.

Remove a rule. Mail from that sender flows normally on the next ingest.