Send your first email
Authenticate with a client certificate, then submit your first message.
Prepare your certificate
Use your application's certificate and private key: client.crt and client.key.
Keep these files secure and readable only by your application.
Send a message
Submit an email using the HTTP API with mTLS authentication. Replace the sender, recipient, and content with your values.
Check the response
A successful request returns 202 Accepted with a message ID.
Connect your application
Application credentials are separate from browser login. Client accounts can use optional passkeys for dashboard access; API and SMTP clients still require mTLS certificates. Verify your sender domain and obtain account approval before creating credentials.
Create credentials in the dashboard
- Open Settings and select Create application credentials.
- Enter Sender addresses, one address under an activated domain per line.
- Optionally enter public HTTPS destinations in Webhook URLs (optional).
- Select Keep the private key on my device (recommended). Generate a local key and public CSR using the example.
- Paste only the CSR into Public signing request, then select Create credentials.
- Save the returned Certificate as
client.crtbeside your application'sclient.key.
Keep the private key private. The certificate authorizes its sender addresses; renewal preserves those addresses and webhook URLs.
Certificate identity
- CN
- Your client identity.
- Email SANs
- Authorized sender addresses.
- URI SANs
- Client webhook destinations.
Sender local parts are case-sensitive and domains are case-insensitive. Keep ownership proof published to retain sender authorization.
Use certificate inspection to check metadata and renewal to rotate credentials.
Send email
Integrate transactional sending, delivery tracking, and failure handling into your application.
Prepare your application
Use an approved client identity, an mTLS client certificate, and a verified sender domain.
The from address must match an email address authorized by your certificate. Keep the domain’s ownership proof published.
Set up client credentials and your sender domain before sending.
Keep the client private key on your server. Use the public HTTPS hostname and verify its certificate.
Examples use the system trust store. For private server certificates, configure your HTTP client’s trusted CA bundle.
Submit a message
Generate one request_id for each intended message and save it before sending.
Reuse that ID and the same payload for retries. Use a new ID for a new intended message.
Do not reuse an ID for different content. Replace the example addresses and request ID with your values.
Send request_id, from, a nonempty to array, and subject to POST /api/v1/send.
Include nonempty body_text or body_html. Include both for clients that prefer different formats.
When you omit body_html, rail generates an HTML alternative from body_text.
Save the acceptance result
HTTP 202 Accepted means rail saved and queued a new message. It does not confirm delivery to the recipient.
Save the returned id with your application record and request_id.
HTTP 200 OK means an accepted request ID was replayed.
The response returns the existing message ID and its stored status, which may already be delivered or bounced.
Deduplication is scoped to your client identity and retained message records.
Keep your own send ledger because retention can remove rail’s deduplication record.
Check each recipient’s delivery
Poll GET /api/v1/messages/{id}/deliveries using the returned message ID.
Use a bounded polling schedule rather than a tight loop.
The response includes an overall message status and one delivery entry per envelope recipient.
The send response and overall message status use these values:
| Status | Meaning |
|---|---|
queued | The send response confirms acceptance. Delivery has not been confirmed. |
pending | Processing or delivery is still in progress. |
partial | Recipient outcomes differ. Inspect each recipient before taking action. |
delivered | Delivery completed. For remote email, the recipient MX accepted the message. |
bounced | Delivery failed. Inspect the recipient diagnostics. |
unroutable | rail could not route the message. Check the message and routing configuration. |
Each recipient’s status is pending, delivered, bounced, or untracked.
untracked means rail has no delivery record for that recipient; read its note.
Local-domain delivery can produce an untracked entry.
Inspect classification, response_code, response, and attempts when diagnosing a recipient.
Some fields are absent when no SMTP response exists.
MX acceptance does not guarantee inbox placement or that someone read the email.
A later delivery status notification can change a recipient from delivered to bounced.
Retry safely
Once rail accepts a message, rail handles downstream delivery retries.
Do not use a new request ID to retry a pending delivery.
| Send result | Application action |
|---|---|
Timeout or connection failure | The send may have been accepted. Retry the same request ID and payload. |
429 | Wait for Retry-After, then retry the same request ID and payload. |
Temporary 5xx | Use bounded exponential backoff with jitter. Honor Retry-After when present. |
503 domain_paused | Restore the sender domain’s ownership proof before retrying. Honor Retry-After. |
400, 401, 403, 413, 422 | Fix the request, credentials, permissions, size, or recipient problem before retrying. |
Set request timeouts, a retry limit, and an overall retry deadline.
Stop retrying after that deadline and reconcile against your saved message record.
Reusing an accepted request ID does not extend rail’s retention period.
HTTP and SMTP status classes differ. SMTP 4xx means a temporary failure; SMTP 5xx means a permanent failure.
Use the HTTP rules above for POST /api/v1/send.
Handle bounces and complaints
Configure the client’s HTTPS webhooks for bounce and complaint notifications. Domain receiving routes do not set those destinations.
Use original_message_id to associate a notification with the sent message.
See Receive email for bounce and complaint payloads.
Require webhook signing and verify signatures using the exact request body.
Use rail’s published signing keys and check the timestamp to reject stale requests.
Dedupe on the stable webhook-id, which remains the same across retries.
Return 2xx promptly after verifying and durably recording the event, then process it asynchronously.
Incoming webhooks use different retry rules from send requests. A 2xx response acknowledges the webhook.
A 4xx response, including 429, stops rail’s retries.
rail retries 5xx responses and transport failures after five minutes, within the configured attempt limit.
Respect recipient_suppressed errors and investigate the recipient problem.
Do not generate new request IDs to retry permanent bounces or bypass complaint suppressions.
Extend the send flow
- Route replies back to your application.
- Send attachments using upload grants or inline files.
- Send over SMTP from an application or an existing Postfix server.
Receive email through webhooks
Receive incoming mail for your domain at a public HTTPS webhook. rail POSTs accepted messages as JSON.
Set up receiving in the dashboard
Verify domain ownership first. Then open Dashboard > Domains and select your domain under Owned domains.
- Find Receiving (optional).
- Enter one public HTTPS URL per line in Receiving webhook URLs, such as
https://app.example.com/hooks/email. - Use Recipient addresses (optional) to limit accepted addresses under this domain. Leave it empty to accept every recipient.
- Check Enable receiving for this domain, then select Save receiving settings.
For records-mode DNS, publish the provided MX record after the receiving destination is ready. Keep existing MX records until then.
For delegated DNS, rail publishes MX after ownership verification and receiving enablement.
These settings route incoming mail for this domain. For API setup, see Domains and forwarding.
Tracked replies can use client webhooks or a configured reply mailbox.
Webhook payload
Bounce notifications
Bounce and complaint notifications use the client’s webhooks. Domain receiving settings do not change those destinations.
A hard bounce produces a notification for the original outbound message. Soft bounces produce no notification.
message_id identifies the event; original_message_id identifies the sent message. The payload has no raw_message.
Complaint notifications
A verified spam complaint produces a notification and suppresses the reported recipient.
message_id identifies the event, and original_message_id links it to the sent message. The payload has no raw_message.
API methods for this task
Route replies
Replies can arrive at a webhook or an email address. The destination depends on your client settings and the message's reply_to.
Choose how replies reach you
| Message setting | Destination | Tracking |
|---|---|---|
| Omit reply_to; a client reply mailbox is configured | The configured email mailbox | rail matches the reply to the original message and forwards it. |
| Omit reply_to; no client reply mailbox is configured | The client's webhooks | rail matches the reply and sends a reply webhook event. |
| Set reply_to explicitly | The address in reply_to | Direct delivery. rail does not track the reply for this message. |
Tracked replies
When you omit reply_to, rail adds Reply-To: reply+<msg_id>@<domain>.
A configured reply mailbox applies to the client across its sender domains. It is separate from domain receiving settings.
Webhooks remain the default when no reply mailbox is configured. Clearing the mailbox restores webhook delivery for new replies.
Changing the destination does not redirect reply deliveries that rail has already planned.
Reply directly to an address on your domain
Set reply_to to an address such as support@example.com to receive replies there directly.
Configure that domain's existing receiving webhook or forward rule to route mail for the address.
This uses normal domain receiving and bypasses tracked reply delivery.
Bounce and complaint notifications
Bounce and complaint notifications continue using the client's webhooks, even when tracked replies use an email mailbox.
Webhook payload type is inbound, reply, bounce, or complaint.
See webhook payload examples and the integration guide for signature verification.
Add a website form
Turn submissions from your website into email. Create a form in the dashboard, then point your HTML form at its public endpoint.
Visitors submit without a client certificate. The form management API requires mTLS.
1. Create a form in the dashboard
Open Dashboard > Forms and select New form.
- Choose an authorized sender in From. This must be an email SAN on your client certificate and cannot change after creation.
- Fill in Name and Subject.
- Enter notification recipients in Recipients (one address per line).
- Set Allowed origins to your website's origin, such as
https://example.com, one per line.https://*.example.comallows the apex and subdomains; empty permits any origin. - Check Enabled, then select Create form.
Copy the created endpoint or the form's Token. You can edit the subject, recipients, origins, and enabled state later.
2. Add the form to your website
Replace FORM_TOKEN with the token from the dashboard. Keep the hidden honeypot field empty.
The email field supplies the submitter's reply address. Other named fields appear in the notification email.
3. Submit a test
A public submission needs no client certificate. Request JSON to read the result from your application.
A successful JSON request returns HTTP 200 with {"ok":true,"id":"01K..."}.
Special fields
These fields control a submission and do not appear in the notification body.
| Field | Purpose |
|---|---|
| _replyto | Set Reply-To explicitly. Invalid addresses are ignored; the email field is the fallback. |
| _subject | Override the form's subject. Line breaks return HTTP 422 invalid_request. |
| _redirect | Override the success redirect only within an allowed origin or the configured redirect's origin. Other values are ignored. |
| _gotcha | Hidden honeypot. Keep it empty. A filled value produces a fake success and no email. |
| _attachment | A file ID from this form's upload grant. Repeat the field for multiple files. |
Accept file uploads
When available, enable Accept file uploads on this form in the dashboard and set its file limits.
- Your page requests
POST /f/{token}/upload-grantusing itsOrigin. No client certificate is needed. - Upload each file directly to the returned
upload_url, withfilenamein the query and the file'sContent-Type. - Submit each returned file ID as an
_attachmentfield. rail sends download links only after every file is servable.
Form grants are valid for 15 minutes and bound to the page's origin. The form's upload policy limits file count, size, and media types.
Use the form grant endpoint above, rather than the mTLS application upload grant. The direct-to-depot upload step is the same.
Do not send file parts to the form endpoint. They return HTTP 422 file_part_rejected.
Responses and limits
| Status | Meaning |
|---|---|
| 200 | JSON success when Accept: application/json is sent, or an HTML success page without a configured redirect. |
| 303 | Successful browser submission redirects to the configured URL. |
| 403 | An origin is not allowed, or a JSON caller receives challenge_required for CAPTCHA verification. |
| 404 | The form token is unknown or disabled. Both return the same response. |
| 413 | The submission or generated message exceeds the size limit. |
| 422 | A field or attachment is invalid, or a file part was submitted directly. |
| 429 | rate_limited. Retry-After indicates when to retry. |
| 503 | The sender domain is paused or attachment processing is temporarily unavailable. |
The default allowance is three submissions per IP per rolling hour across all forms and clients. IPv6 addresses share a /64 allowance.
Per-form, per-client, and request limits can also apply. A submission accepts at most 64 fields or parts, with names up to 256 bytes.
When CAPTCHA is required, browser submissions receive a Turnstile verification page. Clear SQL injection and XSS probes require verification when CAPTCHA is available.
Challenges, honeypot hits, and malformed fields do not consume submission quota. Verified solves do, and later processing failures can consume quota.
API methods for this task
Send attachments
Upload a file, copy its file ID, then include that ID when sending email.
1. Request an upload grant
Call POST /api/v1/upload-grants with your client certificate. This grant accepts one file up to 10 MiB.
Copy upload_url from your response. The grant expires after 15 minutes.
max_files defaults to 1 and accepts at most 10; the service may apply a lower limit.
2. Upload your file
Replace the sample grant URL below with your returned upload_url. Keep ?filename=report.pdf at the end.
Send the file bytes with its Content-Type. This upload uses the grant URL and needs no client certificate.
3. Send the file ID in your message
Replace f_example_report below with the id from your upload response. Replace the sender, recipient, and content too.
Use the file only after the service reports it as servable. A pending scan is not a clean result.
rail appends a download link to your message. attachments and inline files share a limit of 20 entries per message.
Use files uploaded through rail
Files uploaded directly under your own depot certificate are unavailable to rail. Use the grant flow above.
The first client to use a file ID owns it within rail. Another client's ID returns attachment_not_found, like an unknown ID.
See the send request reference for inline files and retry behavior.
API methods for this task
Add a domain and DNS
Register a domain, verify ownership, then use it for sending only or enable receiving.
- Register the domain and choose its DNS mode.
- Publish the returned ownership proof and verify it.
- For sending only, keep the existing MX. To receive through rail, configure a destination and enable receiving.
You can also manage your domains in Dashboard > Domains. New domains start with receiving disabled.
Keep the ownership TXT published in records mode. If proof is removed, restore the current record to resume mail.
Choose a DNS mode
| Mode | What you do | What rail provides |
|---|---|---|
| records | Publish the returned TXT and mail records at your DNS provider. Keep the ownership TXT. | Ownership TXT and DKIM keys, suggested SPF and DMARC policies, and MX when receiving is enabled. |
| delegated | When available, select delegated mode and set both returned nameservers at your registrar or parent DNS provider. Then verify. | nameservers instead of ownership_record. rail hosts mail DNS after verification and adds MX when receiving is enabled. |
Set dns_mode to delegated during registration or PATCH. Adding NS records only inside the child zone does not verify delegation.
Changing modes rotates ownership proof and pauses mail until the new proof verifies. Returning to records mode requires external DNS and the new TXT proof.
Delegated DNS hosts mail records only. rail does not provide website A or AAAA records.
Check sending readiness
Keep receiving_enabled false when another provider hosts your mailboxes. This is independent of DNS mode and ownership status.
Publish the ownership TXT and DKIM keys. Merge SPF authorization with other providers and keep a valid DMARC policy.
Check DNS readiness validates current records without changing ownership state. Sending-only domains skip MX checks.
Sending still requires an authorized certificate sender and verified ownership. A passing DNS check does not activate a pending domain.
API methods for this task
Send over SMTP
Submit email over SMTP on port 465 using a client certificate (mTLS).
For an existing mail server, see Route selected Postfix email through rail.
Use a sender address authorized by your certificate and a verified sender domain. Replace the example addresses with your values.
cURL
Create an RFC 5322 message with CRLF line endings, then submit it over implicit TLS.
Go
Python
Rust
Route selected Postfix email through rail
Use a dedicated transport to relay selected email through rail on port 465.
These examples use Debian or Ubuntu paths, Postfix 3.6 or later, and OpenSSL with TLS 1.3 support.
Replace the SMTP hostname and example addresses with your values.
1. Prepare the client certificate
Obtain a rail client certificate for your sender addresses. Verify the sender domain in rail.
Both the envelope sender (MAIL FROM) and the message’s From address must match authorized certificate addresses.
Prepare client.pem locally: private key first, then the client certificate and issuer chain.
Use an unencrypted key so Postfix can load it without a password prompt. Install the bundle with restricted permissions.
Replace the bundle atomically when rotating certificates, then reload Postfix.
2. Add the rail transport
Append this service to /etc/postfix/master.cf.
The transport requires implicit TLS 1.3, verifies the server hostname, and presents your client certificate.
rail authenticates the certificate without SMTP AUTH credentials.
The empty policy and fallback settings prevent inherited destination policies or fallback relays from overriding this transport.
The CA path trusts public server certificates, including ACME certificates.
For a private-CA server certificate, replace smtp_tls_CAfile with the server’s trusted CA bundle.
The client certificate’s issuing CA may differ from the server’s CA. Keep these TLS settings on the dedicated transport.
3. Select email by envelope sender
Add the lookup table to sender_dependent_default_transport_maps in /etc/postfix/main.cf.
Preserve existing tables and check their lookup order. Create /etc/postfix/rail_senders with an exact sender match.
Square brackets select the SMTP host directly without an MX lookup. Unmatched senders keep their existing routing.
This setting applies to remote recipients in Postfix’s default address class. Existing transport_maps entries take precedence.
Local, virtual, and relay-domain deliveries use their own transport settings.
Build and query the sender table. Check that postconf -m lists hash, or use a supported map type.
Optional: select recipients instead
Use transport_maps instead of the sender table when selecting mail by recipient.
Preserve existing tables and check their lookup order. Use the same dedicated rail transport.
Every selected message still needs certificate-authorized envelope and From addresses.
A recipient mapping does not authorize additional senders. Build and query the recipient table instead.
4. Check the configuration and send a test
Check the service definition and configuration, then reload Postfix.
Replace both addresses before testing. Use an authorized sender and a destination mailbox you control.
For recipient-based routing, use the recipient in your lookup table.
Check the Postfix log for postfix/rail and the rail SMTP host as the relay.
A 250 response after DATA means rail queued the message.
Check the message’s per-recipient delivery status in rail to confirm downstream acceptance.
Postfix retries temporary SMTP 4xx failures before acceptance. Permanent SMTP 5xx failures require correction before resubmission.
After rail accepts the message, rail handles downstream delivery retries.
See Postfix’s sender routing, TLS configuration, transport tables, and service definitions.
Client API reference
Every application method, public form flow, and certificate API is listed below. Examples are static and never send requests from this page.
Choose a resource folder in the sidebar, then select one HTTP method. Task walkthroughs live under Guides.
Sending
- POST
/api/v1/sendSend an email - POST
/v1/sendLegacy alias for POST /api/v1/send
Messages and testing
- GET
/api/v1/messagesList your messages - GET
/api/v1/messages/{id}Get one of your messages - GET
/api/v1/messages/{id}/deliveriesGet delivery status for a message - GET
/api/v1/messages/{id}/opensGet open-tracking events for a message - POST
/api/v1/testSend a test email - GET
/api/v1/test/reply/{msg_id}Poll for a test email reply
Upload grants
- POST
/api/v1/upload-grantsMint a depot upload grant for a send attachment
Domains and forwarding
- GET
/api/v1/domainsList owned domains - POST
/api/v1/domainsRegister a client domain - GET
/api/v1/domains/{domain}Read an owned domain - PATCH
/api/v1/domains/{domain}Update domain routing - DELETE
/api/v1/domains/{domain}Release a domain - GET
/api/v1/domains/{domain}/recordsRead public DNS records - POST
/api/v1/domains/{domain}/checkCheck DNS readiness - POST
/api/v1/domains/{domain}/verifyVerify domain ownership - GET
/api/v1/domains/{domain}/forwardsList forwarding rules - POST
/api/v1/domains/{domain}/forwardsAdd a forwarding rule - PATCH
/api/v1/domains/{domain}/forwards/{local_part}/{destination}Update a forwarding rule - DELETE
/api/v1/domains/{domain}/forwards/{local_part}/{destination}Remove a forwarding rule
Forms
- POST
/api/v1/formsCreate a form target - GET
/api/v1/formsList your form targets - GET
/api/v1/forms/{token}Get one form target - PATCH
/api/v1/forms/{token}Partially update a form target - DELETE
/api/v1/forms/{token}Delete a form target - GET
/api/v1/forms/{token}/submissionsList a form's persisted submissions - GET
/api/v1/forms/{token}/submissions/{id}Get one persisted submission - POST
/f/{token}Submit an HTML form - OPTIONS
/f/{token}Check form CORS permissions - POST
/f/{token}/upload-grantMint a depot upload grant for a form - OPTIONS
/f/{token}/upload-grantCheck form CORS permissions
Webhook signing
- GET
/.well-known/jwks.jsonGet webhook signing public keys
Certificate inspection
Certificate renewal
- POST
/api/v1/certs/renewRenew your client certificate - POST
/certs/renewRenew an already-expired certificate
Send an email
/api/v1/sendmTLS client certificate · application/json
Queue a transactional email. The sender must be authorized by your certificate and its domain must be verified. At least one body field is required.
Request body
request_idstring requiredClient-supplied idempotency key, echoed in response
Minimum length: 1fromstring requiredSingle email address, optionally with a display name; its bare address must match a certificate email SAN.
Minimum length: 1 · Format: emailtostring[] requiredRecipient addresses
Minimum entries: 1ccstring[] optionalCC recipients
subjectstring required- Minimum length: 1
body_textstring optionalPlain-text body. When body_html is omitted, rail auto-generates an HTML alternative from this text and sends multipart/alternative.
body_htmlstring optionalHTML body. At least one body field is required and must be nonempty.
reply_tostring optionalOverride Reply-To (disables VERP tracking when set)
Format: emailunsubscribe_urlstring optionalAdds one-click unsubscribe headers. Must not contain CR/LF; URL syntax is not validated.
attachmentsstring[] optionalFile IDs from rail upload grants. Each becomes a download link; attachments and files share a limit of 20.
Maximum entries: 20filesobject[] optionalInline files become download links. Upload and scanning finish before acceptance. An accepted request_id retry uploads nothing.
Maximum entries: 20Item fields
filenamestring required- Minimum length: 1
content_typestring optionalDefaults to application/octet-stream
Default: "application/octet-stream"contentstring requiredStandard base64, padded; must not be empty
Minimum length: 1 · Format: byte
At least one body field is required. The combined attachments and files limit is 20. Only accepted request IDs are safe to replay without another upload.
Success response
200 OK — Replay of an accepted request_id; returns the existing message and stored status
application/json: SendResponse
202 Accepted — New message accepted and queued
application/json: SendResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid request |
| 403 | Sender not authorized by certificate |
| 413 | Request too large (error codes "message_too_large", or "attachment_too_large" when depot refuses a files[] entry). |
| 422 | Unprocessable request — e.g. invalid address, too many recipients, a recipient on this client's suppression list (error code "recipient_suppressed"), or an attachment problem (error codes "attachments_not_supported", "attachment_not_found", "attachment_infected", "attachment_not_ready", "attachment_unavailable", "attachment_rejected", "too_many_attachments"). |
| 503 | Temporarily unavailable. |
| 429 | Retry-After gives the wait in seconds. |
| 401 | Client certificate required or expired (unauthorized) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
SendResponse
idstring requiredMessage ID (ULID)
request_idstring requiredEchoed from request
recipientsinteger requiredNumber of recipients queued
statusstring requiredqueued for a new send; the stored message status for an accepted request_id replay.
Values: "queued", "pending", "partial", "delivered", "bounced", "unroutable"
Optional fields
| Field | Type | Behavior |
|---|---|---|
| reply_to | string | Send replies directly to this address. This disables tracked replies for the message. |
| body_html | string | HTML alternative. If omitted, rail generates HTML from body_text. Supply at least one body field. |
| cc | string[] | CC recipients. These count toward the message's recipient limit. |
| unsubscribe_url | string | Add DKIM-signed List-Unsubscribe and List-Unsubscribe-Post headers for one-click unsubscribe (RFC 8058). |
Attachments
Both attachment options add download links to the message body.
| Field | Use it for |
|---|---|
| attachments | File IDs uploaded through upload grants. Pass an array of IDs, such as ["f_example_report"]. |
| files | Inline files. Each object requires filename and padded base64 content. content_type is optional and defaults to application/octet-stream. |
attachments and files share a limit of 20 entries per message.
Inline uploads wait for upload and scanning. Retrying an accepted request_id uploads nothing and returns the existing message.
Oversized inline files return HTTP 413 attachment_too_large. Rejected inline files return HTTP 422 attachment_rejected.
Complete request with optional fields
Replace the addresses and example file ID with your values. The inline file contains the text Hello.
Authenticated API requests recheck certificate expiry on persistent connections. After expiry, requests return HTTP 401 unauthorized.
A paused sender domain returns HTTP 503 domain_paused with Retry-After. Keep the ownership TXT record published.
List your messages
/api/v1/messagesmTLS client certificate
List only your client’s messages, newest first. Return next_before as before to continue; a full final page may be followed by an empty page.
Query parameters
statusstring optional- Values: "pending", "partial", "delivered", "bounced", "unroutable"
senderstring optionalCase-insensitive substring of the From address.
recipientstring optionalCase-insensitive substring of any envelope recipient.
sincestring optionalInclusive lower bound on created_at (RFC3339 or YYYY-MM-DD).
untilstring optionalInclusive upper bound on created_at.
limitinteger optionalPage size. Values above 200 are clamped to 200.
Default: 50 · Minimum: 1 · Maximum: 200beforestring optionalContinue after this message id (a previous next_before).
Request body: none.
Success response
200 OK — One page of messages
application/json: MessageListResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid filter or limit |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
MessageListResponse
messagesMessageSummary[] requirednext_beforestring optionalPresent when the page was full; the next page may be empty.
Get one of your messages
/api/v1/messages/{id}mTLS client certificate
Read one owned message. attachments is an array of file details here; list rows contain an attachment count instead. File IDs and download URLs are not returned.
Path parameters
idstring required
Request body: none.
Success response
200 OK — Message metadata
application/json: MessageDetail
Errors and retry behavior
| Status | Meaning |
|---|---|
| 404 | No such message for this client |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
MessageDetail
idstring requiredrequest_idstring optionalstatusstring requireddirectionstring requiredfromstring requiredtostring[] requiredsizeinteger requiredcreated_atstring required- Format: date-time
updated_atstring required- Format: date-time
first_opened_atstring optional- Format: date-time
open_summaryOpenSummary optionalattachmentsMessageAttachment[] requiredThe files the message carried, in order: send attachments, form uploads, or inbound parts rail uploaded to depot. Empty when there are none. The depot file id and download URL are never returned.
OpenSummary
totalinteger requiredSum of the four counts below
clientinteger requiredLikely a human opened it
proxyinteger requiredA mail provider's image proxy rendered it (e.g. Gmail's GoogleImageProxy)
prefetchinteger requiredAn automated fetch at delivery time, no human
unknowninteger requiredNo signal was available
Get delivery status for a message
/api/v1/messages/{id}/deliveriesmTLS client certificate
Read each envelope recipient’s delivery state. untracked means no delivery record exists; its note explains why and attempts is zero.
Path parameters
idstring required
Request body: none.
Success response
200 OK — Per-recipient delivery status
application/json: MessageDeliveriesResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 404 | No such message for this client |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
MessageDeliveriesResponse
message_idstring requiredstatusstring requireddeliveriesRecipientDelivery[] required
Get open-tracking events for a message
/api/v1/messages/{id}/opensmTLS client certificate
Read recorded open events and counts by classification. The method remains available when tracking is disabled and can return an empty opens array.
Path parameters
idstring required
Request body: none.
Success response
200 OK — Recorded open events and classification counts
application/json: MessageOpensResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 404 | No such message for this client |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
MessageOpensResponse
message_idstring requiredfirst_opened_atstring optional- Format: date-time
opensMessageOpen[] requiredsummaryobject requiredOpen counts by classification, across the opens array
Object fields
clientinteger requiredproxyinteger requiredprefetchinteger requiredunknowninteger required
Mint a depot upload grant for a send attachment
/api/v1/upload-grantsmTLS client certificate · application/json
Request a 15-minute grant for uploading attachments. Copy the returned upload_url and POST file bytes there without a client certificate, then send its file ID.
Request body
max_bytesinteger requiredRequired, > 0. Per-file size cap in bytes.
Minimum: 1max_filesinteger optionalFiles allowed by this grant. The service may apply a lower limit.
Default: 1 · Minimum: 1 · Maximum: 10content_typesstring[] optionalOptional allowlist of media types (max 20 entries).
Maximum entries: 20file_ttlstring optionalOptional Go duration string, such as "24h"; must be positive. It limits a file no send uses. An accepted send keeps each attached file for at least depot's default retention.
originsstring[] optionalAllowed scheme://host origins for browser uploads. Defaults to the service origin; up to 10 entries.
Maximum entries: 10
Success response
201 Created — Grant minted
application/json: UploadGrantResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Malformed JSON, wrong Content-Type, missing/zero max_bytes, max_files/content_types/origins out of range, or a non-positive/unparseable file_ttl (error code "invalid_request") |
| 413 | Request body exceeds the maximum size (error code "request_too_large") |
| 422 | Attachments not supported (error code "attachments_not_supported" — depot is not configured), or depot refused the grant parameters (error code "grant_refused"; the message is depot's own) |
| 429 | Retry-After gives the wait in seconds. |
| 503 | depot_unavailable — depot is unreachable, errored, or (401/403/404/ 429/5xx) refused the mint for a reason that is not the caller's own input; a 404 here usually means grants are disabled in depot's own config |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
UploadGrantResponse
upload_urlstring required- Format: uri
expires_atstring required- Format: date-time
max_filesinteger requiredmax_bytesinteger requiredcontent_typesstring[] optionalfile_ttlstring optionalGo duration string, echoing what was sent to depot; omitted when not set
List owned domains
/api/v1/domainsmTLS client certificate
List owned domains
Query parameters
limitinteger optionalMaximum records per page
Default: 100 · Minimum: 1 · Maximum: 100afterstring optionalThe next_cursor from the previous response
Request body: none.
Success response
200 OK — Success
application/json: DomainListResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainListResponse
domainsDomainResponse[] requirednext_cursorstring optional
Register a client domain
/api/v1/domainsmTLS client certificate · application/json
Register a client domain
Request body
domainstring required- Maximum length: 253
dns_modestring optionalChoose records or, when available, delegated DNS. Delegated mode requires fresh parent nameserver proof.
Default: "records" · Values: "records", "delegated"
Success response
201 Created — Success
application/json: DomainResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainDNSRecord
namestring requiredtypestring required- Values: "TXT", "MX", "NS"
valuestring required
DomainResponse
domainstring requiredstatusstring required- Values: "pending", "verified", "unverified", "disabled"
dns_modestring required- Values: "records", "delegated"
receiving_enabledboolean requiredwebhook_urlsstring[] requiredmailboxesstring[] requiredownership_recordDomainDNSRecord optionalOwnership TXT for records mode; omitted for delegated mode.
nameserversstring[] optionalImmutable assigned nameservers for delegated mode; omitted for records mode.
Minimum entries: 2 · Maximum entries: 2verified_atstring | null required- Format: date-time
last_checked_atstring | null required- Format: date-time
created_atstring required- Format: date-time
updated_atstring required- Format: date-time
Read an owned domain
/api/v1/domains/{domain}mTLS client certificate
Read an owned domain
Path parameters
domainstring requiredOwned domain name
Request body: none.
Success response
200 OK — Success
application/json: DomainResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainDNSRecord
namestring requiredtypestring required- Values: "TXT", "MX", "NS"
valuestring required
DomainResponse
domainstring requiredstatusstring required- Values: "pending", "verified", "unverified", "disabled"
dns_modestring required- Values: "records", "delegated"
receiving_enabledboolean requiredwebhook_urlsstring[] requiredmailboxesstring[] requiredownership_recordDomainDNSRecord optionalOwnership TXT for records mode; omitted for delegated mode.
nameserversstring[] optionalImmutable assigned nameservers for delegated mode; omitted for records mode.
Minimum entries: 2 · Maximum entries: 2verified_atstring | null required- Format: date-time
last_checked_atstring | null required- Format: date-time
created_atstring required- Format: date-time
updated_atstring required- Format: date-time
Update domain routing
/api/v1/domains/{domain}mTLS client certificate · application/json
Update receiving routes or DNS mode. Supplied arrays replace their values; empty clears and omitted fields stay unchanged. Enabling receiving requires verified ownership and a destination.
Path parameters
domainstring requiredOwned domain name
Request body
dns_modestring optionalActual mode changes rotate proof and pause the domain until fresh proof succeeds.
Values: "records", "delegated"webhook_urlsstring[] optional- Maximum entries: 20
mailboxesstring[] optional- Maximum entries: 1000
receiving_enabledboolean optional
Success response
200 OK — Success
application/json: DomainResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainDNSRecord
namestring requiredtypestring required- Values: "TXT", "MX", "NS"
valuestring required
DomainResponse
domainstring requiredstatusstring required- Values: "pending", "verified", "unverified", "disabled"
dns_modestring required- Values: "records", "delegated"
receiving_enabledboolean requiredwebhook_urlsstring[] requiredmailboxesstring[] requiredownership_recordDomainDNSRecord optionalOwnership TXT for records mode; omitted for delegated mode.
nameserversstring[] optionalImmutable assigned nameservers for delegated mode; omitted for records mode.
Minimum entries: 2 · Maximum entries: 2verified_atstring | null required- Format: date-time
last_checked_atstring | null required- Format: date-time
created_atstring required- Format: date-time
updated_atstring required- Format: date-time
Read public DNS records
/api/v1/domains/{domain}/recordsmTLS client certificate
Read a domain snapshot and DNS guidance. Records mode returns ownership TXT and DKIM keys.
MX appears only when receiving is enabled. SPF and DMARC values are examples, not exact-match requirements.
Merge SPF authorization with existing providers and preserve valid DMARC policies and report destinations.
Delegated mode returns assigned NS records for your registrar. Use DNS checks to validate current records.
Path parameters
domainstring requiredOwned domain name
Request body: none.
Success response
200 OK — DNS guidance for the current domain settings
application/json: DomainRecordsResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 503 | Domain management unavailable |
Field and response shapes
DomainRecordsResponse
domainstring requireddns_modestring requiredValues: records, delegated.
receiving_enabledboolean requiredFalse means sending only. MX checks and guidance do not apply.
recordsDomainDNSGuidanceRecord[] requiredPublic records and policy examples.
DomainDNSGuidanceRecord
namestring requiredtypestring requiredValues: TXT, MX, NS.
valuestring requiredpurposestring requiredValues: ownership, receiving, spf, dkim, dmarc.
requirementstring requiredValues: required, recommended. SPF and DMARC values are recommended examples.
Check domain DNS readiness
/api/v1/domains/{domain}/checkmTLS client certificate
Check current DNS without changing ownership status, observation timestamps, missing-proof counters, or ownership audit events.
The check verifies ownership TXT or parent delegation, SPF, DMARC, and the held DKIM public keys.
Sending-only domains skip MX. Receiving domains can use rail as a secondary MX.
Combined SPF providers and valid custom DMARC policies pass. DKIM checks compare parsed public keys.
Missing or incompatible evidence produces fail. Lookup failures produce error within a 200 response.
Checks have a 20-second limit. They share 10 requests per minute per client with registration, verification, and DNS-mode changes.
Passing checks neither activate a pending domain nor guarantee delivery. Use ownership verification to record evidence.
Path parameters
domainstring requiredOwned domain name
Request body: none.
Success response
200 OK — Diagnostic results, including failed or incomplete checks
application/json: DomainCheckResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 429 | Domain operation rate limit reached. Retry-After gives the wait in seconds. |
| 503 | Domain management unavailable |
Field and response shapes
DomainCheckResponse
domainstring requireddns_modestring requiredValues: records, delegated.
receiving_enabledboolean requiredFalse means sending only. MX checks and guidance do not apply.
checked_atstring requiredFormat: date-time.
resultsDomainCheckResult[] required
DomainCheckResult
checkstring requiredValues: dns.ownership, dns.mx, dns.spf, dns.dmarc, dkim.key.
subjectstring requiredDomain or selector-qualified DNS name.
statusstring requiredValues: pass, warn, fail, skip, error.
observedstring optionalwantstring optionaldetailstring optional
Verify domain ownership
/api/v1/domains/{domain}/verifymTLS client certificate
Check the domain’s current ownership proof. Restore missing proof before retrying; temporary DNS failures do not count as missing proof.
Path parameters
domainstring requiredOwned domain name
Request body: none.
Success response
200 OK — Success
application/json: DomainResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainDNSRecord
namestring requiredtypestring required- Values: "TXT", "MX", "NS"
valuestring required
DomainResponse
domainstring requiredstatusstring required- Values: "pending", "verified", "unverified", "disabled"
dns_modestring required- Values: "records", "delegated"
receiving_enabledboolean requiredwebhook_urlsstring[] requiredmailboxesstring[] requiredownership_recordDomainDNSRecord optionalOwnership TXT for records mode; omitted for delegated mode.
nameserversstring[] optionalImmutable assigned nameservers for delegated mode; omitted for records mode.
Minimum entries: 2 · Maximum entries: 2verified_atstring | null required- Format: date-time
last_checked_atstring | null required- Format: date-time
created_atstring required- Format: date-time
updated_atstring required- Format: date-time
Release a domain
/api/v1/domains/{domain}mTLS client certificate
Release the domain and its forwarding rules. Replace or revoke every credential referencing the domain first; expired, unrevoked certificates can still reserve it.
Path parameters
domainstring requiredOwned domain name
Request body: none.
Success response
204 No Content — Success
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
List forwarding rules
/api/v1/domains/{domain}/forwardsmTLS client certificate
List forwarding rules
Path parameters
domainstring requiredOwned domain name
Query parameters
limitinteger optionalMaximum records per page
Default: 100 · Minimum: 1 · Maximum: 100afterstring optionalThe next_cursor from the previous response
Request body: none.
Success response
200 OK — Success
application/json: DomainForwardListResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainForwardListResponse
forwardsDomainForwardResponse[] requirednext_cursorstring optional
Add a forwarding rule
/api/v1/domains/{domain}/forwardsmTLS client certificate · application/json
Forward an address such as support@example.net to help@example.org. Enable receiving and publish MX after the destination is ready.
Re-enabling clears hard-bounce suppression only. Complaint and manual suppressions remain and appear in still_suppressed_reason.
Path parameters
domainstring requiredOwned domain name
Request body
local_partstring requireddestinationstring required- Format: email
from_mungingstring optional- Default: "" · Values: "", "inherit", "never", "always", "auto", "arc"
Success response
201 Created — Success
application/json: DomainForwardResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainForwardResponse
local_partstring requireddestinationstring requiredenabledboolean requiredfrom_mungingstring requiredconsecutive_failuresinteger required- Format: int64
disabled_atstring | null required- Format: date-time
disabled_reasonstring requiredcreated_atstring required- Format: date-time
Update a forwarding rule
/api/v1/domains/{domain}/forwards/{local_part}/{destination}mTLS client certificate · application/json
Update one alias and destination pair. Encode each path segment separately; help@example.org becomes help%40example.org. inherit is normalized to an empty override.
Re-enabling clears hard-bounce suppression only. Complaint and manual suppressions remain and appear in still_suppressed_reason.
Path parameters
domainstring requiredOwned domain name
local_partstring requiredURL-encoded forwarding local part
destinationstring requiredURL-encoded destination email address
Request body
enabledboolean optionalfrom_mungingstring optional- Values: "", "inherit", "never", "always", "auto", "arc"
Success response
200 OK — Success
application/json: DomainForwardUpdateResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
DomainForwardResponse
local_partstring requireddestinationstring requiredenabledboolean requiredfrom_mungingstring requiredconsecutive_failuresinteger required- Format: int64
disabled_atstring | null required- Format: date-time
disabled_reasonstring requiredcreated_atstring required- Format: date-time
DomainForwardUpdateResponse
forwardDomainForwardResponse requiredsuppression_clearedboolean requiredstill_suppressed_reasonstring optional
Remove a forwarding rule
/api/v1/domains/{domain}/forwards/{local_part}/{destination}mTLS client certificate
Remove this one forwarding rule. The alias and destination together identify the rule.
Path parameters
domainstring requiredOwned domain name
local_partstring requiredURL-encoded forwarding local part
destinationstring requiredURL-encoded destination email address
Request body: none.
Success response
204 No Content — Success
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields, or invalid values |
| 401 | Client certificate required |
| 403 | Client disabled or account not approved |
| 404 | Missing resource or owned by another client |
| 409 | Ownership conflict, missing proof, active certificate reference, or quota reached |
| 413 | JSON request exceeds 64 KiB |
| 429 | Retry-After gives the wait in seconds. |
| 503 | DNS lookup or domain management unavailable |
Create a form target
/api/v1/formsmTLS client certificate · application/json
Create a form owned by your client. from must match a certificate email SAN and cannot be changed later. No client certificate is needed for visitors submitting to the public token.
Request body
namestring requiredHuman label, shown as the heading of submission emails Maximum 200 UTF-8 bytes.
Minimum length: 1fromstring requiredSender address (must match a cert email SAN) Maximum 320 UTF-8 bytes.
Minimum length: 1 · Format: emailtostring[] requiredRecipients of submission emails
Minimum entries: 1subjectstring requiredDefault subject (submitters can override via _subject) Maximum 255 UTF-8 bytes.
Minimum length: 1redirect_urlstring optionalPost-submit redirect for browser form posts Maximum 2048 UTF-8 bytes.
Format: uriallowed_originsstring[] optionalOrigins allowed to submit: exact (https://example.com) or wildcard (https://*.example.com, matches the apex and any-depth subdomains). Normalized to lowercase; empty = any origin
Maximum entries: 20rate_limitinteger optionalSubmissions/hour for this form, 0-10000 (0 = service default)
Default: 0 · Minimum: 0 · Maximum: 10000cc_submitterboolean optionalCC the submitter's extracted email (the email/_replyto field) on each submission. Copies are silently skipped when the address is suppressed or over the global per-address rate limit.
Default: falsefield_labelsobject optionalMap submitted field names to display labels. At most 64 entries; labels are at most 200 UTF-8 bytes.
uploadsFormUploads optional
Success response
201 Created — Form target created
application/json: FormResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid request |
| 403 | from address not permitted by client certificate |
| 413 | Request body exceeds the maximum size |
| 422 | Invalid address, origin, redirect URL, rate limit (0-10000), field length, or the per-client form quota is exhausted (error code "quota_exceeded") |
| 401 | Client certificate required or expired (unauthorized) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormResponse
tokenstring requiredPublic form token — POST target is /f/{token}
namestring requiredfromstring requiredtostring[] requiredsubjectstring requiredredirect_urlstring optionalallowed_originsstring[] optionalrate_limitinteger requiredcc_submitterboolean requiredfield_labelsobject optionalenabledboolean requiredcreated_atstring required- Format: date-time
cert_serialstring optionalSerial of the client certificate that authorized this form; submissions are refused once that certificate is revoked
uploadsFormUploads optional
FormUploads
max_filesinteger optionalFiles per submission, 1-10 (0 = uploads off)
Default: 0 · Minimum: 0 · Maximum: 10max_bytesinteger optionalPer-file size cap in bytes (0 = 10 MiB; max 1 GiB)
Default: 10485760 · Minimum: 0 · Maximum: 1073741824content_typesstring[] optionalBare media types such as application/pdf (max 20; empty = any)
Maximum entries: 20ttlstring optionalGo duration from zero through 8760h. Empty or zero uses the service default.
List your form targets
/api/v1/formsmTLS client certificate
List your own form targets. This response is a JSON array, with no pagination query.
Request body: none.
Success response
200 OK — Form targets
application/json: FormResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormResponse
tokenstring requiredPublic form token — POST target is /f/{token}
namestring requiredfromstring requiredtostring[] requiredsubjectstring requiredredirect_urlstring optionalallowed_originsstring[] optionalrate_limitinteger requiredcc_submitterboolean requiredfield_labelsobject optionalenabledboolean requiredcreated_atstring required- Format: date-time
cert_serialstring optionalSerial of the client certificate that authorized this form; submissions are refused once that certificate is revoked
uploadsFormUploads optional
FormUploads
max_filesinteger optionalFiles per submission, 1-10 (0 = uploads off)
Default: 0 · Minimum: 0 · Maximum: 10max_bytesinteger optionalPer-file size cap in bytes (0 = 10 MiB; max 1 GiB)
Default: 10485760 · Minimum: 0 · Maximum: 1073741824content_typesstring[] optionalBare media types such as application/pdf (max 20; empty = any)
Maximum entries: 20ttlstring optionalGo duration from zero through 8760h. Empty or zero uses the service default.
Get one form target
/api/v1/forms/{token}mTLS client certificate
Read one form target. Foreign and missing tokens both return 404.
Path parameters
tokenstring required
Request body: none.
Success response
200 OK — Form target
application/json: FormResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 404 | Unknown token, or owned by another client |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormResponse
tokenstring requiredPublic form token — POST target is /f/{token}
namestring requiredfromstring requiredtostring[] requiredsubjectstring requiredredirect_urlstring optionalallowed_originsstring[] optionalrate_limitinteger requiredcc_submitterboolean requiredfield_labelsobject optionalenabledboolean requiredcreated_atstring required- Format: date-time
cert_serialstring optionalSerial of the client certificate that authorized this form; submissions are refused once that certificate is revoked
uploadsFormUploads optional
FormUploads
max_filesinteger optionalFiles per submission, 1-10 (0 = uploads off)
Default: 0 · Minimum: 0 · Maximum: 10max_bytesinteger optionalPer-file size cap in bytes (0 = 10 MiB; max 1 GiB)
Default: 10485760 · Minimum: 0 · Maximum: 1073741824content_typesstring[] optionalBare media types such as application/pdf (max 20; empty = any)
Maximum entries: 20ttlstring optionalGo duration from zero through 8760h. Empty or zero uses the service default.
Partially update a form target
/api/v1/forms/{token}mTLS client certificate · application/json
Change only supplied editable fields. Empty strings, arrays, and objects clear values. from, token, and client_id remain immutable and are ignored if supplied.
Path parameters
tokenstring required
Request body
namestring optionalHuman label, shown as the heading of submission emails Maximum 200 UTF-8 bytes.
Minimum length: 1tostring[] optionalRecipients of submission emails
Minimum entries: 1subjectstring optionalDefault subject (submitters can override via _subject) Maximum 255 UTF-8 bytes.
Minimum length: 1redirect_urlstring optionalPost-submit redirect for browser form posts Maximum 2048 UTF-8 bytes.
Format: uriallowed_originsstring[] optionalOrigins allowed to submit: exact (https://example.com) or wildcard (https://*.example.com, matches the apex and any-depth subdomains). Normalized to lowercase; empty = any origin
Maximum entries: 20rate_limitinteger optionalSubmissions/hour for this form, 0-10000 (0 = service default)
Minimum: 0 · Maximum: 10000cc_submitterboolean optionalCC the submitter's extracted email (the email/_replyto field) on each submission. Copies are silently skipped when the address is suppressed or over the global per-address rate limit.
field_labelsobject optionalMap submitted field names to display labels. At most 64 entries; labels are at most 200 UTF-8 bytes.
uploadsFormUploads optionalenabledboolean optionalEnable or disable this form.
Success response
200 OK — Updated form target
application/json: FormResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid request, or a required field (name/subject/to) was cleared |
| 404 | Unknown token, or owned by another client |
| 413 | Request body exceeds the maximum size |
| 422 | Invalid address, origin, redirect URL, rate limit (0-10000), or field length |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormResponse
tokenstring requiredPublic form token — POST target is /f/{token}
namestring requiredfromstring requiredtostring[] requiredsubjectstring requiredredirect_urlstring optionalallowed_originsstring[] optionalrate_limitinteger requiredcc_submitterboolean requiredfield_labelsobject optionalenabledboolean requiredcreated_atstring required- Format: date-time
cert_serialstring optionalSerial of the client certificate that authorized this form; submissions are refused once that certificate is revoked
uploadsFormUploads optional
FormUploads
max_filesinteger optionalFiles per submission, 1-10 (0 = uploads off)
Default: 0 · Minimum: 0 · Maximum: 10max_bytesinteger optionalPer-file size cap in bytes (0 = 10 MiB; max 1 GiB)
Default: 10485760 · Minimum: 0 · Maximum: 1073741824content_typesstring[] optionalBare media types such as application/pdf (max 20; empty = any)
Maximum entries: 20ttlstring optionalGo duration from zero through 8760h. Empty or zero uses the service default.
Delete a form target
/api/v1/forms/{token}mTLS client certificate
Delete your own form target. The response is HTTP 200 with deleted and token fields, rather than an empty 204 response.
Path parameters
tokenstring required
Request body: none.
Success response
200 OK — Deleted
deletedboolean required- Value: true
tokenstring required
application/json: object
Errors and retry behavior
| Status | Meaning |
|---|---|
| 404 | Unknown token, or owned by another client |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
List a form's persisted submissions
/api/v1/forms/{token}/submissionsmTLS client certificate
List accepted submissions newest first. format=csv exports all rows and ignores before and limit. Accept: text/csv selects CSV only when format is absent.
Path parameters
tokenstring required
Query parameters
beforestring optionalKeyset cursor — the id of the last row from a previous page. Ignored with format=csv.
limitinteger optionalPage size, default 50, capped at 100. Ignored with format=csv.
Default: 50 · Minimum: 1 · Maximum: 100formatstring optionalCase-insensitive csv selects every row as CSV. Unknown values are ignored. An explicit format suppresses Accept-based CSV selection.
Request body: none.
Success response
200 OK — Submissions (JSON), or every submission as CSV when format=csv or Accept:text/csv
application/json: FormSubmissionsResponse
text/csv: string
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Unparsable limit |
| 404 | Unknown token, or owned by another client |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormSubmissionsResponse
submissionsFormSubmissionResponse[] requiredcountinteger requirednext_beforestring optionalCursor for the next page; present only when this page was full
Get one persisted submission
/api/v1/forms/{token}/submissions/{id}mTLS client certificate
Read one submission within its form. A submission under a different form returns 404 even if your client owns both forms.
Path parameters
tokenstring requiredidstring required
Request body: none.
Success response
200 OK — Submission
application/json: FormSubmissionResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 404 | Unknown id, or belonging to a different form |
| 401 | Client certificate required or expired (unauthorized) |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormSubmissionResponse
idstring requiredform_tokenstring requiredform_namestring requiredSnapshot of the form's name at submission time
message_idstring requiredThe outbound message this submission produced
fieldsobject[] requiredSubmitted (name, value) pairs, in submission order
Item fields
namestring requiredvaluestring required
truncatedboolean requiredTrue when a field value was capped (total name+value bytes over 16KiB); the field name is always kept whole
subjectstring requiredreply_tostring requiredsource_ipstring requireduser_agentstring requiredCapped at 128 bytes
originstring requiredThe submitting request's Origin header, verbatim
spam_scoreinteger | null requiredNull when never classified (captcha off, or a solved challenge, which skips re-classification)
spam_reasonsstring[] | null requiredoutcomestring required- Values: "clean", "challenge_solved", "unscored"
attachmentsobject[] optionalThe depot files this submission carried, as resolved at submit time. Omitted when it carried none. The url keeps working until the file reaches the form's uploads.ttl, which is independent of how long this row is retained.
Item fields
idstring requireddepot file id
namestring requiredFilename as depot recorded it, capped at 255 bytes
sizeinteger required- Format: int64
typestring optionaldepot's parsed media type
urlstring optionaldepot download link
created_atstring required- Format: date-time
Submit an HTML form
/f/{token}Public · no client certificate · application/x-www-form-urlencoded or multipart/form-data
Submit at least one ordinary text field. Accept: application/json selects JSON; browser submissions redirect or show an HTML result. File parts are refused: use _attachment IDs instead.
Path parameters
tokenstring required
Request body
_replytostring optionalReply email address; invalid values are ignored.
emailstring optionalOrdinary content field and fallback reply address.
_subjectstring optionalSubject override; CR/LF is rejected.
_redirectstring optionalAllowed success redirect override.
_gotchastring optionalHoneypot: leave empty.
_challengestring optionalCAPTCHA nonce returned by challenge_required.
cf-turnstile-responsestring optionalCAPTCHA widget token returned after solving.
_attachmentstring[] optionalRepeat this field for each file ID from the form upload grant; limited by the form policy.
At least one non-reserved text field is required. A normal email field is optional; names accept at most 256 UTF-8 bytes. At most 64 fields or parts are accepted.
Success response
200 OK — JSON success, HTML success when no redirect is configured, or browser CAPTCHA interstitial
application/json: FormSubmitResponse
text/html: string
303 See Other — Submission accepted — redirect to the form's success URL
For JSON CAPTCHA challenges, repost the same fields plus _challenge from the returned nonce and cf-turnstile-response from the solved widget. Failed solves report verify_failed or verify_unavailable.
Errors and retry behavior
| Status | Meaning |
|---|---|
| 403 | The origin is not allowed, or a JSON caller needs CAPTCHA verification (challenge_required). |
| 404 | Unknown or disabled form token |
| 413 | Request body or rendered message exceeds the maximum size |
| 415 | Content-Type is not urlencoded or multipart form data |
| 422 | Invalid submission (e.g. line breaks in _subject, too many fields) |
| 429 | Retry-After gives the wait in seconds. |
| 503 | The form's From domain is paused because its ownership TXT record is missing (error code "domain_paused"); Retry-After is 300. |
| 400 | Malformed input, missing ordinary fields, invalid file ID, or overlong field name |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
FormSubmitResponse
okboolean required- Value: true
idstring required
Mint a depot upload grant for a form
/f/{token}/upload-grantPublic · no client certificate
Request an upload grant for this form’s policy and page origin. Supply a usable Origin, or a Referer whose origin can be used. No request body or client certificate is needed.
Path parameters
tokenstring required
Header parameters
Originstring optionalPage origin. A usable Referer-derived origin is accepted when Origin is absent or null.
Refererstring optionalFallback source of the page origin.
Request body: none.
Success response
201 Created — Grant minted
application/json: UploadGrantResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | origin_required — no usable Origin or Referer on the request |
| 403 | Origin not permitted for this form |
| 404 | Unknown or disabled form token |
| 422 | uploads_not_enabled — the form has no upload policy |
| 429 | Retry-After gives the wait in seconds. |
| 503 | depot_unavailable — depot is not configured or the mint failed |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
UploadGrantResponse
upload_urlstring required- Format: uri
expires_atstring required- Format: date-time
max_filesinteger requiredmax_bytesinteger requiredcontent_typesstring[] optionalfile_ttlstring optionalGo duration string, echoing what was sent to depot; omitted when not set
Get webhook signing public keys
/.well-known/jwks.jsonPublic · no client certificate
Fetch public keys for webhook signature verification. Keys are Ed25519/EdDSA, with active or retiring status; x contains a base64url public key.
Request body: none.
Success response
200 OK — Active and retiring public signing keys; empty keys array when signing is disabled
application/json: WebhookKeySet
Errors and retry behavior
| Status | Meaning |
|---|---|
| 429 | Retry-After gives the wait in seconds. |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
WebhookKeySet
keysPublicJWK[] required
Inspect your client certificate
/whomTLS client certificate
Inspect the certificate presented over mTLS. Accept: application/json is required for this API response; otherwise /who serves its inspection page. Verdict failures still return HTTP 200.
Header parameters
Acceptstring requiredSelects JSON certificate inspection. Other Accept values serve the HTML inspection page.
Value: "application/json"
Request body: none.
Success response
200 OK — Certificate details
application/json: WhoResponse
text/html: string
Errors and retry behavior
| Status | Meaning |
|---|---|
| 401 | JSON inspection requires a client certificate |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
WhoResponse
client_idstring requiredsendersstring[] requiredwebhooksstring[] requiredvalidboolean requiredkey_typestring requirednot_beforestring required- Format: date-time
not_afterstring required- Format: date-time
expires_in_daysinteger requiredWhole days until expiry, truncated toward zero; recently expired certificates can still read 0.
renew_recommendedboolean requiredTrue when the certificate is inside the service renewal window, including expired certificates.
serialstring requiredrevokedboolean requiredreasonsstring[] requiredwebhook_signing_enabledboolean requiredwebhook_signing_key_idstring optional
Inspect any certificate
/whoPublic · no client certificate · application/x-pem-file
Upload a public PEM certificate, never its private key. Anonymous responses omit valid and revoked. An accepted mTLS identity receives the full verdict.
Request body
string · required. Raw public PEM certificate, read up to 64 KiB.
Success response
200 OK — Certificate details
application/json: WhoResponse or AnonymousWhoResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Empty, unreadable, malformed PEM, or invalid certificate |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
AnonymousWhoResponse
client_idstring requiredsendersstring[] requiredwebhooksstring[] requiredkey_typestring requirednot_beforestring required- Format: date-time
not_afterstring required- Format: date-time
expires_in_daysinteger requiredWhole days until expiry, truncated toward zero; recently expired certificates can still read 0.
renew_recommendedboolean requiredTrue when the certificate is inside the service renewal window, including expired certificates.
serialstring requiredreasonsstring[] requiredwebhook_signing_enabledboolean requiredwebhook_signing_key_idstring optional
WhoResponse
client_idstring requiredsendersstring[] requiredwebhooksstring[] requiredvalidboolean requiredkey_typestring requirednot_beforestring required- Format: date-time
not_afterstring required- Format: date-time
expires_in_daysinteger requiredWhole days until expiry, truncated toward zero; recently expired certificates can still read 0.
renew_recommendedboolean requiredTrue when the certificate is inside the service renewal window, including expired certificates.
serialstring requiredrevokedboolean requiredreasonsstring[] requiredwebhook_signing_enabledboolean requiredwebhook_signing_key_idstring optional
Renew your client certificate
/api/v1/certs/renewmTLS client certificate · application/json
Renew using the newest active certificate and a CSR for a different Ed25519 or ECDSA P-256 key. Sender addresses, identity, and webhook URLs are preserved.
JSON bodies must fit 64 KiB and reject unknown fields. Only public certificate and CSR material belongs in the request.
Generate a new key and CSR before renewing. A certificate must reach the service minimum age; 429 renew_too_soon provides Retry-After.
Request body
csr_pemstring requiredPEM-encoded certificate signing request for a new key (Ed25519 or ECDSA P-256); must not reuse the presented certificate's key
Minimum length: 1
Success response
200 OK — Certificate renewed
application/json: CertRenewResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Malformed JSON, missing or invalid CSR, an unsupported key, or a CSR reusing the current certificate key. |
| 403 | The presented certificate is not the client's current certificate (error code "renew_not_current"), or client approval, enrollment, disablement, or activated sender ownership rejects renewal (error code "cert_invalid") |
| 413 | Request body exceeds the maximum size (error code "request_too_large") |
| 429 | Retry-After gives the wait in seconds. |
| 503 | Certificate renewal is not configured (error code "unavailable") |
| 500 | Certificate renewal failed |
| 401 | Client certificate required or expired (unauthorized) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
CertRenewResponse
cert_pemstring requiredThe new, PEM-encoded certificate. Never a private key.
serialstring requiredNew certificate's serial, lowercase hex
not_afterstring required- Format: date-time
previous_serialstring requiredSerial of the certificate presented for the request (mTLS)
active_certsinteger requiredThe client's active certificate count after this renewal (at most 2)
Renew an already-expired certificate
/certs/renewPublic · no client certificate · application/json
Renew an expired certificate without presenting it in the TLS handshake. The CSR must prove the same key as the expired certificate; submit public certificate and CSR material only.
JSON bodies must fit 64 KiB and reject unknown fields. Only public certificate and CSR material belongs in the request.
Use your existing private key to create the CSR. Proof refusals share a uniform 400 invalid_request; after proof succeeds, renewal policy can still return 429 renew_too_soon.
Request body
cert_pemstring requiredPEM-encoded, already-expired certificate to renew
Minimum length: 1csr_pemstring requiredPEM-encoded certificate signing request carrying the SAME key as cert_pem (Ed25519 or ECDSA P-256) -- proof the caller holds the certificate's private key
Minimum length: 1
Success response
200 OK — Certificate renewed
application/json: CertRenewResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Malformed input or a uniformly refused certificate, expiry, sender ownership, or key proof. |
| 413 | Request body exceeds the maximum size (error code "request_too_large") |
| 429 | Retry-After gives the wait in seconds. |
| 503 | Certificate renewal is not configured (error code "unavailable") |
| 500 | Certificate renewal failed |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
CertRenewResponse
cert_pemstring requiredThe new, PEM-encoded certificate. Never a private key.
serialstring requiredNew certificate's serial, lowercase hex
not_afterstring required- Format: date-time
previous_serialstring requiredSerial of the certificate presented for the request (mTLS)
active_certsinteger requiredThe client's active certificate count after this renewal (at most 2)
Send a test email
/api/v1/testmTLS client certificate · application/json
Send a test email from the first sender address on your certificate. Test reply tracking lasts approximately one hour and is not durable across service restarts.
Request body
tostring requiredOne email address, optionally with a display name.
Minimum length: 1
Success response
202 Accepted — Test message queued
application/json: TestSendResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Missing to, malformed JSON, wrong Content-Type, or no certificate email SAN |
| 401 | Client certificate required |
| 403 | Client certificate validation failed |
| 422 | Invalid address or suppressed recipient |
| 429 | Retry-After gives the wait in seconds. |
| 500 | Message could not be queued |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
TestSendResponse
idstring requiredfromstring requiredtostring requiredstatusstring required- Values: "queued"
Poll for a test email reply
/api/v1/test/reply/{msg_id}mTLS client certificate
Poll a test message sent by your client. A pending reply returns 204; an unknown, foreign, expired, or non-test message returns 404.
Path parameters
msg_idstring required
Request body: none.
Success response
200 OK — Inbound reply received
application/json: TestReplyResponse
204 No Content — No reply has arrived
Errors and retry behavior
| Status | Meaning |
|---|---|
| 401 | Client certificate required |
| 404 | Unknown, foreign, expired-tracker, or non-test message |
| 500 | Reply lookup failed |
| 403 | Certificate or client identity rejected (cert_invalid) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
TestReplyResponse
fromstring requiredsubjectstring requiredbodystring requiredReply body capped at 4000 bytes.
received_atstring required- Format: date-time
Legacy alias for POST /api/v1/send
/v1/sendmTLS client certificate · application/json
Compatibility alias for POST /api/v1/send. It uses the same authentication, request fields, errors, and response shapes.
Request body
SendRequest: see the canonical send fields. The types and required fields are identical.
Success response
200 OK — Replay of an accepted request_id; returns the existing message and stored status
application/json: SendResponse
202 Accepted — New message accepted and queued
application/json: SendResponse
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid request |
| 403 | Sender not authorized by certificate |
| 413 | Request too large (error codes "message_too_large", or "attachment_too_large" when depot refuses a files[] entry). |
| 422 | Unprocessable request — e.g. invalid address, too many recipients, a recipient on this client's suppression list (error code "recipient_suppressed"), or an attachment problem (error codes "attachments_not_supported", "attachment_not_found", "attachment_infected", "attachment_not_ready", "attachment_unavailable", "attachment_rejected", "too_many_attachments"). |
| 503 | Temporarily unavailable. |
| 429 | Retry-After gives the wait in seconds. |
| 401 | Client certificate required or expired (unauthorized) |
Field and response shapes
Expand a linked shape to inspect its field types. Response examples show selected fields.
SendResponse
idstring requiredMessage ID (ULID)
request_idstring requiredEchoed from request
recipientsinteger requiredNumber of recipients queued
statusstring requiredqueued for a new send; the stored message status for an accepted request_id replay.
Values: "queued", "pending", "partial", "delivered", "bounced", "unroutable"
Check form CORS permissions
/f/{token}Public · no client certificate
Check CORS permission for a browser origin. The response has no body; CORS headers appear only for an allowed origin and eligible form.
Path parameters
tokenstring required
Header parameters
Originstring optional
Request body: none.
Success response
204 No Content — No body; CORS headers are returned only for an allowed origin and eligible form
Check form CORS permissions
/f/{token}/upload-grantPublic · no client certificate
Check browser CORS permission for a form upload grant. The response is 204, with allowed-origin headers only when eligible.
Path parameters
tokenstring required
Header parameters
Originstring optional
Request body: none.
Success response
204 No Content — No body; CORS headers are returned only for an allowed origin and eligible form
Check email and verify ownership
Enable email_checks with a fixed probe sender on a rail-owned domain. Changes require restart. All four endpoints require an operational mTLS identity.
Check deliverability
Submit one bare mailbox. Results are valid, invalid, undeliverable, or unknown. Each client can make 60 checks per minute per server process. JSON requests must fit 4,096 bytes. Successful MX handoffs supply global evidence fresh for 30 days. MX recipient acceptance alone is provisional.
MX, A, and AAAA lookups share bounded caches. Positive answers use delivery.mx_cache_ttl, negative answers last one minute, and transient errors last 15 seconds. Every SMTP probe has a separate durable 24-hour cooldown, including failures. A probe sends no message.
Known receiving domains use routing: local and reason: local_domain from the live receiving-domain registry. Observed MX presence and classification remain unchanged. Local routes never initiate SMTP probes. Without stronger evidence, return unknown/local_domain with smtp.result: not_run and smtp.reason: local_domain. Fresh delivery and mailbox-failure evidence retain precedence. Local routing and recipient acceptance do not prove mailbox validity; recipient_accepted remains provisional.
Assessment examples
Selected fields from separate responses:
{"status":"valid","reason":"recent_delivery"}
{"status":"invalid","reason":"mailbox_not_found"}
{"status":"undeliverable","reason":"mailbox_full"}
{"status":"unknown","reason":"recipient_accepted"}Classify domains
Categories: business, free, paid, disposable, privacy relay, education, government, nonprofit, custom, and unknown. Nullable traits distinguish temporary and single-use behavior. Categories do not automatically block delivery. MX hosting does not determine a recipient domain's category.
A configured local index imports Disposable’s GitHub provider registry and normal disposable feed. It checks on startup and every six hours using conditional requests. Changed data commits transactionally; failed updates retain the last successful data. Indexed results include the source URL and a sha256: dataset digest. Unmatched domains use inferred business, independently of DNS routing or probe permission. The inferred fallback uses source business_default and policy version rail-business-default-v1. It does not prove company ownership or mailbox validity. API requests use local classification lookups only.
Confirm ownership
Create a challenge for an address, purpose, and application subject. Submit the six-digit code through the owning client's backend. Codes expire after ten minutes and allow five failed attempts. Resend after 60 seconds; five sends per client/address/purpose/hour and 20 per destination/hour. Reusing an accepted request ID sends nothing.
Global delivery evidence cannot verify ownership for another client or purpose. Pixel fetches cannot consume challenges. Proxy opens remain indeterminate.
Methods
| Method | Purpose |
|---|---|
POST /api/v1/emails/check | Check an email address |
POST /api/v1/email-verifications | Create an ownership verification |
POST /api/v1/email-verifications/{id}/confirm | Confirm mailbox ownership |
GET /api/v1/email-verifications/{id} | Get an ownership verification |
Check an email address
/api/v1/emails/checkmTLS client certificate
Assess routing, domain classification, recipient rejection, and recent global delivery evidence. All DNS queries use bounded caches. Every attempted recipient probe has a durable 24-hour cooldown. Successful delivery evidence remains fresh for 30 days. HTTP 200 includes unknown and invalid results.
Known receiving domains use routing: local and reason: local_domain from the live receiving-domain registry. Observed MX presence and classification remain unchanged. Local routes never initiate SMTP probes. Without stronger evidence, return unknown/local_domain with smtp.result: not_run and smtp.reason: local_domain. Fresh delivery and mailbox-failure evidence retain precedence. Local routing and recipient acceptance do not prove mailbox validity; recipient_accepted remains provisional.
Limit: 60 checks per minute per client per server process. Probe capacity: 16 per process, two per MX hostname. JSON body limit: 4,096 bytes.
Request fields
emailstring required
Response
Schema: EmailCheckResult. See OpenAPI for complete field types and enums.
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code |
| 401 | Client certificate required or expired |
| 403 | Client identity rejected or sender_not_authorized |
| 413 | JSON request exceeds 4096 bytes |
| 429 | rate_limited; Retry-After gives a wait in seconds |
| 503 | feature_disabled, domain_paused, or unavailable infrastructure |
Create an ownership verification
/api/v1/email-verificationsmTLS client certificate
Send a six-digit code for the client, address, purpose, and application subject. Codes expire in ten minutes and allow five failed attempts. Replaying an accepted request_id sends nothing and returns 200. Resending uses a new request_id and preserves the challenge expiry and failed-attempt budget.
Required label byte limits: purpose 64, subject_id 256, request_id 128. Reject empty values and control characters. The JSON body must fit 4,096 bytes.
Request fields
emailstring requiredfromstring required- Authorized certificate sender
purposestring requiredsubject_idstring requiredrequest_idstring required
Response
Schema: EmailVerificationResponse. See OpenAPI for complete field types and enums.
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code |
| 401 | Client certificate required or expired |
| 403 | Client identity rejected or sender_not_authorized |
| 413 | JSON request exceeds 4096 bytes |
| 422 | recipient_suppressed for this client |
| 429 | rate_limited; Retry-After gives a wait in seconds |
| 503 | feature_disabled, domain_paused, or unavailable infrastructure |
| 409 | request_conflict: request_id already used with different fields |
Confirm mailbox ownership
/api/v1/email-verifications/{id}/confirmmTLS client certificate
Atomically consume a code for the owning client. Wrong, expired, locked, and consumed codes all return invalid_code. Pixel fetches and link inspection cannot confirm ownership.
Request fields
codestring required
Response
Schema: EmailVerificationResponse. See OpenAPI for complete field types and enums.
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code |
| 401 | Client certificate required or expired |
| 403 | Client identity rejected or sender_not_authorized |
| 413 | JSON request exceeds 4096 bytes |
| 429 | rate_limited; Retry-After gives a wait in seconds |
| 503 | feature_disabled, domain_paused, or unavailable infrastructure |
| 404 | Challenge missing or owned by another client |
Get an ownership verification
/api/v1/email-verifications/{id}mTLS client certificate
Read the owning client's challenge status. Foreign and missing challenges both return 404. Verification for another client or purpose cannot authorize this application.
Response
Schema: EmailVerificationResponse. See OpenAPI for complete field types and enums.
Errors and retry behavior
| Status | Meaning |
|---|---|
| 400 | Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code |
| 401 | Client certificate required or expired |
| 403 | Client identity rejected or sender_not_authorized |
| 413 | JSON request exceeds 4096 bytes |
| 429 | rate_limited; Retry-After gives a wait in seconds |
| 503 | feature_disabled, domain_paused, or unavailable infrastructure |
| 404 | Challenge missing or owned by another client |