Documentation
Operational

Send your first email

Authenticate with a client certificate, then submit your first message.

Before you start: an approved account, a verified sender domain, and a client certificate.

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

  1. Open Settings and select Create application credentials.
  2. Enter Sender addresses, one address under an activated domain per line.
  3. Optionally enter public HTTPS destinations in Webhook URLs (optional).
  4. Select Keep the private key on my device (recommended). Generate a local key and public CSR using the example.
  5. Paste only the CSR into Public signing request, then select Create credentials.
  6. Save the returned Certificate as client.crt beside your application's client.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:

StatusMeaning
queuedThe send response confirms acceptance. Delivery has not been confirmed.
pendingProcessing or delivery is still in progress.
partialRecipient outcomes differ. Inspect each recipient before taking action.
deliveredDelivery completed. For remote email, the recipient MX accepted the message.
bouncedDelivery failed. Inspect the recipient diagnostics.
unroutablerail 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 resultApplication action
Timeout or connection failureThe send may have been accepted. Retry the same request ID and payload.
429Wait for Retry-After, then retry the same request ID and payload.
Temporary 5xxUse bounded exponential backoff with jitter. Honor Retry-After when present.
503 domain_pausedRestore the sender domain’s ownership proof before retrying. Honor Retry-After.
400, 401, 403, 413, 422Fix 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

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.

  1. Find Receiving (optional).
  2. Enter one public HTTPS URL per line in Receiving webhook URLs, such as https://app.example.com/hooks/email.
  3. Use Recipient addresses (optional) to limit accepted addresses under this domain. Leave it empty to accept every recipient.
  4. 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 settingDestinationTracking
Omit reply_to; a client reply mailbox is configuredThe configured email mailboxrail matches the reply to the original message and forwards it.
Omit reply_to; no client reply mailbox is configuredThe client's webhooksrail matches the reply and sends a reply webhook event.
Set reply_to explicitlyThe address in reply_toDirect 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.

  1. Choose an authorized sender in From. This must be an email SAN on your client certificate and cannot change after creation.
  2. Fill in Name and Subject.
  3. Enter notification recipients in Recipients (one address per line).
  4. Set Allowed origins to your website's origin, such as https://example.com, one per line. https://*.example.com allows the apex and subdomains; empty permits any origin.
  5. 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.

FieldPurpose
_replytoSet Reply-To explicitly. Invalid addresses are ignored; the email field is the fallback.
_subjectOverride the form's subject. Line breaks return HTTP 422 invalid_request.
_redirectOverride the success redirect only within an allowed origin or the configured redirect's origin. Other values are ignored.
_gotchaHidden honeypot. Keep it empty. A filled value produces a fake success and no email.
_attachmentA 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.

  1. Your page requests POST /f/{token}/upload-grant using its Origin. No client certificate is needed.
  2. Upload each file directly to the returned upload_url, with filename in the query and the file's Content-Type.
  3. Submit each returned file ID as an _attachment field. 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

StatusMeaning
200JSON success when Accept: application/json is sent, or an HTML success page without a configured redirect.
303Successful browser submission redirects to the configured URL.
403An origin is not allowed, or a JSON caller receives challenge_required for CAPTCHA verification.
404The form token is unknown or disabled. Both return the same response.
413The submission or generated message exceeds the size limit.
422A field or attachment is invalid, or a file part was submitted directly.
429rate_limited. Retry-After indicates when to retry.
503The 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.

Your account only: every request uses mTLS. The certificate CN selects the owning client; foreign and missing resources both return 404.
  1. Register the domain and choose its DNS mode.
  2. Publish the returned ownership proof and verify it.
  3. 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

ModeWhat you doWhat rail provides
recordsPublish 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.
delegatedWhen 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

Messages and testing

Upload grants

Domains and forwarding

Forms

Webhook signing

Certificate inspection

Certificate renewal

Send an email

POST/api/v1/send

mTLS 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_id string required

Client-supplied idempotency key, echoed in response

Minimum length: 1
from string required

Single email address, optionally with a display name; its bare address must match a certificate email SAN.

Minimum length: 1 · Format: email
to string[] required

Recipient addresses

Minimum entries: 1
cc string[] optional

CC recipients

subject string required
Minimum length: 1
body_text string optional

Plain-text body. When body_html is omitted, rail auto-generates an HTML alternative from this text and sends multipart/alternative.

body_html string optional

HTML body. At least one body field is required and must be nonempty.

reply_to string optional

Override Reply-To (disables VERP tracking when set)

Format: email
unsubscribe_url string optional

Adds one-click unsubscribe headers. Must not contain CR/LF; URL syntax is not validated.

attachments string[] optional

File IDs from rail upload grants. Each becomes a download link; attachments and files share a limit of 20.

Maximum entries: 20
files object[] optional

Inline files become download links. Upload and scanning finish before acceptance. An accepted request_id retry uploads nothing.

Maximum entries: 20
Item fields
filename string required
Minimum length: 1
content_type string optional

Defaults to application/octet-stream

Default: "application/octet-stream"
content string required

Standard 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
StatusMeaning
400Invalid request
403Sender not authorized by certificate
413Request too large (error codes "message_too_large", or "attachment_too_large" when depot refuses a files[] entry).
422Unprocessable 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").
503Temporarily unavailable.
429Retry-After gives the wait in seconds.
401Client certificate required or expired (unauthorized)

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

SendResponse
id string required

Message ID (ULID)

request_id string required

Echoed from request

recipients integer required

Number of recipients queued

status string required

queued for a new send; the stored message status for an accepted request_id replay.

Values: "queued", "pending", "partial", "delivered", "bounced", "unroutable"

Optional fields

FieldTypeBehavior
reply_tostringSend replies directly to this address. This disables tracked replies for the message.
body_htmlstringHTML alternative. If omitted, rail generates HTML from body_text. Supply at least one body field.
ccstring[]CC recipients. These count toward the message's recipient limit.
unsubscribe_urlstringAdd 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.

FieldUse it for
attachmentsFile IDs uploaded through upload grants. Pass an array of IDs, such as ["f_example_report"].
filesInline 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

GET/api/v1/messages

mTLS 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

status string optional
Values: "pending", "partial", "delivered", "bounced", "unroutable"
sender string optional

Case-insensitive substring of the From address.

recipient string optional

Case-insensitive substring of any envelope recipient.

since string optional

Inclusive lower bound on created_at (RFC3339 or YYYY-MM-DD).

until string optional

Inclusive upper bound on created_at.

limit integer optional

Page size. Values above 200 are clamped to 200.

Default: 50 · Minimum: 1 · Maximum: 200
before string optional

Continue 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
StatusMeaning
400Invalid filter or limit
401Client certificate required or expired (unauthorized)
403Certificate 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
messages MessageSummary[] required
next_before string optional

Present when the page was full; the next page may be empty.

Get one of your messages

GET/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

id string required

Request body: none.

Success response

200 OK — Message metadata

application/json: MessageDetail

Errors and retry behavior
StatusMeaning
404No such message for this client
401Client certificate required or expired (unauthorized)
403Certificate 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
id string required
request_id string optional
status string required
direction string required
from string required
to string[] required
size integer required
created_at string required
Format: date-time
updated_at string required
Format: date-time
first_opened_at string optional
Format: date-time
open_summary OpenSummary optional

See OpenSummary fields.

attachments MessageAttachment[] required

The 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
total integer required

Sum of the four counts below

client integer required

Likely a human opened it

proxy integer required

A mail provider's image proxy rendered it (e.g. Gmail's GoogleImageProxy)

prefetch integer required

An automated fetch at delivery time, no human

unknown integer required

No signal was available

Get delivery status for a message

GET/api/v1/messages/{id}/deliveries

mTLS 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

id string required

Request body: none.

Success response

200 OK — Per-recipient delivery status

application/json: MessageDeliveriesResponse

Errors and retry behavior
StatusMeaning
404No such message for this client
401Client certificate required or expired (unauthorized)
403Certificate 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_id string required
status string required
deliveries RecipientDelivery[] required

Get open-tracking events for a message

GET/api/v1/messages/{id}/opens

mTLS 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

id string required

Request body: none.

Success response

200 OK — Recorded open events and classification counts

application/json: MessageOpensResponse

Errors and retry behavior
StatusMeaning
404No such message for this client
401Client certificate required or expired (unauthorized)
403Certificate 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_id string required
first_opened_at string optional
Format: date-time
opens MessageOpen[] required
summary object required

Open counts by classification, across the opens array

Object fields
client integer required
proxy integer required
prefetch integer required
unknown integer required

Mint a depot upload grant for a send attachment

POST/api/v1/upload-grants

mTLS 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_bytes integer required

Required, > 0. Per-file size cap in bytes.

Minimum: 1
max_files integer optional

Files allowed by this grant. The service may apply a lower limit.

Default: 1 · Minimum: 1 · Maximum: 10
content_types string[] optional

Optional allowlist of media types (max 20 entries).

Maximum entries: 20
file_ttl string optional

Optional 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.

origins string[] optional

Allowed 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
StatusMeaning
400Malformed 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")
413Request body exceeds the maximum size (error code "request_too_large")
422Attachments 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)
429Retry-After gives the wait in seconds.
503depot_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
401Client certificate required or expired (unauthorized)
403Certificate 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_url string required
Format: uri
expires_at string required
Format: date-time
max_files integer required
max_bytes integer required
content_types string[] optional
file_ttl string optional

Go duration string, echoing what was sent to depot; omitted when not set

List owned domains

GET/api/v1/domains

mTLS client certificate

List owned domains

Query parameters

limit integer optional

Maximum records per page

Default: 100 · Minimum: 1 · Maximum: 100
after string optional

The next_cursor from the previous response

Request body: none.

Success response

200 OK — Success

application/json: DomainListResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

DomainListResponse
domains DomainResponse[] required
next_cursor string optional

Register a client domain

POST/api/v1/domains

mTLS client certificate · application/json

Register a client domain

Request body

domain string required
Maximum length: 253
dns_mode string optional

Choose 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
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

DomainDNSRecord
name string required
type string required
Values: "TXT", "MX", "NS"
value string required
DomainResponse
domain string required
status string required
Values: "pending", "verified", "unverified", "disabled"
dns_mode string required
Values: "records", "delegated"
receiving_enabled boolean required
webhook_urls string[] required
mailboxes string[] required
ownership_record DomainDNSRecord optional

Ownership TXT for records mode; omitted for delegated mode.

See DomainDNSRecord fields.

nameservers string[] optional

Immutable assigned nameservers for delegated mode; omitted for records mode.

Minimum entries: 2 · Maximum entries: 2
verified_at string | null required
Format: date-time
last_checked_at string | null required
Format: date-time
created_at string required
Format: date-time
updated_at string required
Format: date-time

Read an owned domain

GET/api/v1/domains/{domain}

mTLS client certificate

Read an owned domain

Path parameters

domain string required

Owned domain name

Request body: none.

Success response

200 OK — Success

application/json: DomainResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

DomainDNSRecord
name string required
type string required
Values: "TXT", "MX", "NS"
value string required
DomainResponse
domain string required
status string required
Values: "pending", "verified", "unverified", "disabled"
dns_mode string required
Values: "records", "delegated"
receiving_enabled boolean required
webhook_urls string[] required
mailboxes string[] required
ownership_record DomainDNSRecord optional

Ownership TXT for records mode; omitted for delegated mode.

See DomainDNSRecord fields.

nameservers string[] optional

Immutable assigned nameservers for delegated mode; omitted for records mode.

Minimum entries: 2 · Maximum entries: 2
verified_at string | null required
Format: date-time
last_checked_at string | null required
Format: date-time
created_at string required
Format: date-time
updated_at string required
Format: date-time

Update domain routing

PATCH/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

domain string required

Owned domain name

Request body

dns_mode string optional

Actual mode changes rotate proof and pause the domain until fresh proof succeeds.

Values: "records", "delegated"
webhook_urls string[] optional
Maximum entries: 20
mailboxes string[] optional
Maximum entries: 1000
receiving_enabled boolean optional

Success response

200 OK — Success

application/json: DomainResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

DomainDNSRecord
name string required
type string required
Values: "TXT", "MX", "NS"
value string required
DomainResponse
domain string required
status string required
Values: "pending", "verified", "unverified", "disabled"
dns_mode string required
Values: "records", "delegated"
receiving_enabled boolean required
webhook_urls string[] required
mailboxes string[] required
ownership_record DomainDNSRecord optional

Ownership TXT for records mode; omitted for delegated mode.

See DomainDNSRecord fields.

nameservers string[] optional

Immutable assigned nameservers for delegated mode; omitted for records mode.

Minimum entries: 2 · Maximum entries: 2
verified_at string | null required
Format: date-time
last_checked_at string | null required
Format: date-time
created_at string required
Format: date-time
updated_at string required
Format: date-time

Read public DNS records

GET/api/v1/domains/{domain}/records

mTLS 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

domain string required

Owned domain name

Request body: none.

Success response

200 OK — DNS guidance for the current domain settings

application/json: DomainRecordsResponse

Errors and retry behavior
StatusMeaning
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
503Domain management unavailable

Field and response shapes

DomainRecordsResponse
domain string required
dns_mode string required

Values: records, delegated.

receiving_enabled boolean required

False means sending only. MX checks and guidance do not apply.

records DomainDNSGuidanceRecord[] required

Public records and policy examples.

DomainDNSGuidanceRecord
name string required
type string required

Values: TXT, MX, NS.

value string required
purpose string required

Values: ownership, receiving, spf, dkim, dmarc.

requirement string required

Values: required, recommended. SPF and DMARC values are recommended examples.

Check domain DNS readiness

POST/api/v1/domains/{domain}/check

mTLS 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

domain string required

Owned domain name

Request body: none.

Success response

200 OK — Diagnostic results, including failed or incomplete checks

application/json: DomainCheckResponse

Errors and retry behavior
StatusMeaning
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
429Domain operation rate limit reached. Retry-After gives the wait in seconds.
503Domain management unavailable

Field and response shapes

DomainCheckResponse
domain string required
dns_mode string required

Values: records, delegated.

receiving_enabled boolean required

False means sending only. MX checks and guidance do not apply.

checked_at string required

Format: date-time.

results DomainCheckResult[] required
DomainCheckResult
check string required

Values: dns.ownership, dns.mx, dns.spf, dns.dmarc, dkim.key.

subject string required

Domain or selector-qualified DNS name.

status string required

Values: pass, warn, fail, skip, error.

observed string optional
want string optional
detail string optional

Verify domain ownership

POST/api/v1/domains/{domain}/verify

mTLS 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

domain string required

Owned domain name

Request body: none.

Success response

200 OK — Success

application/json: DomainResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

DomainDNSRecord
name string required
type string required
Values: "TXT", "MX", "NS"
value string required
DomainResponse
domain string required
status string required
Values: "pending", "verified", "unverified", "disabled"
dns_mode string required
Values: "records", "delegated"
receiving_enabled boolean required
webhook_urls string[] required
mailboxes string[] required
ownership_record DomainDNSRecord optional

Ownership TXT for records mode; omitted for delegated mode.

See DomainDNSRecord fields.

nameservers string[] optional

Immutable assigned nameservers for delegated mode; omitted for records mode.

Minimum entries: 2 · Maximum entries: 2
verified_at string | null required
Format: date-time
last_checked_at string | null required
Format: date-time
created_at string required
Format: date-time
updated_at string required
Format: date-time

Release a domain

DELETE/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

domain string required

Owned domain name

Request body: none.

Success response

204 No Content — Success

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

List forwarding rules

GET/api/v1/domains/{domain}/forwards

mTLS client certificate

List forwarding rules

Path parameters

domain string required

Owned domain name

Query parameters

limit integer optional

Maximum records per page

Default: 100 · Minimum: 1 · Maximum: 100
after string optional

The next_cursor from the previous response

Request body: none.

Success response

200 OK — Success

application/json: DomainForwardListResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

DomainForwardListResponse
forwards DomainForwardResponse[] required
next_cursor string optional

Add a forwarding rule

POST/api/v1/domains/{domain}/forwards

mTLS 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

domain string required

Owned domain name

Request body

local_part string required
destination string required
Format: email
from_munging string optional
Default: "" · Values: "", "inherit", "never", "always", "auto", "arc"

Success response

201 Created — Success

application/json: DomainForwardResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS 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_part string required
destination string required
enabled boolean required
from_munging string required
consecutive_failures integer required
Format: int64
disabled_at string | null required
Format: date-time
disabled_reason string required
created_at string required
Format: date-time

Update a forwarding rule

PATCH/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

domain string required

Owned domain name

local_part string required

URL-encoded forwarding local part

destination string required

URL-encoded destination email address

Request body

enabled boolean optional
from_munging string optional
Values: "", "inherit", "never", "always", "auto", "arc"

Success response

200 OK — Success

application/json: DomainForwardUpdateResponse

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS 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_part string required
destination string required
enabled boolean required
from_munging string required
consecutive_failures integer required
Format: int64
disabled_at string | null required
Format: date-time
disabled_reason string required
created_at string required
Format: date-time
DomainForwardUpdateResponse
suppression_cleared boolean required
still_suppressed_reason string optional

Remove a forwarding rule

DELETE/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

domain string required

Owned domain name

local_part string required

URL-encoded forwarding local part

destination string required

URL-encoded destination email address

Request body: none.

Success response

204 No Content — Success

Errors and retry behavior
StatusMeaning
400Invalid JSON, unknown fields, or invalid values
401Client certificate required
403Client disabled or account not approved
404Missing resource or owned by another client
409Ownership conflict, missing proof, active certificate reference, or quota reached
413JSON request exceeds 64 KiB
429Retry-After gives the wait in seconds.
503DNS lookup or domain management unavailable

Create a form target

POST/api/v1/forms

mTLS 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

name string required

Human label, shown as the heading of submission emails Maximum 200 UTF-8 bytes.

Minimum length: 1
from string required

Sender address (must match a cert email SAN) Maximum 320 UTF-8 bytes.

Minimum length: 1 · Format: email
to string[] required

Recipients of submission emails

Minimum entries: 1
subject string required

Default subject (submitters can override via _subject) Maximum 255 UTF-8 bytes.

Minimum length: 1
redirect_url string optional

Post-submit redirect for browser form posts Maximum 2048 UTF-8 bytes.

Format: uri
allowed_origins string[] optional

Origins 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: 20
rate_limit integer optional

Submissions/hour for this form, 0-10000 (0 = service default)

Default: 0 · Minimum: 0 · Maximum: 10000
cc_submitter boolean optional

CC 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: false
field_labels object optional

Map submitted field names to display labels. At most 64 entries; labels are at most 200 UTF-8 bytes.

Success response

201 Created — Form target created

application/json: FormResponse

Errors and retry behavior
StatusMeaning
400Invalid request
403from address not permitted by client certificate
413Request body exceeds the maximum size
422Invalid address, origin, redirect URL, rate limit (0-10000), field length, or the per-client form quota is exhausted (error code "quota_exceeded")
401Client certificate required or expired (unauthorized)

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

FormResponse
token string required

Public form token — POST target is /f/{token}

name string required
from string required
to string[] required
subject string required
redirect_url string optional
allowed_origins string[] optional
rate_limit integer required
cc_submitter boolean required
field_labels object optional
enabled boolean required
created_at string required
Format: date-time
cert_serial string optional

Serial of the client certificate that authorized this form; submissions are refused once that certificate is revoked

FormUploads
max_files integer optional

Files per submission, 1-10 (0 = uploads off)

Default: 0 · Minimum: 0 · Maximum: 10
max_bytes integer optional

Per-file size cap in bytes (0 = 10 MiB; max 1 GiB)

Default: 10485760 · Minimum: 0 · Maximum: 1073741824
content_types string[] optional

Bare media types such as application/pdf (max 20; empty = any)

Maximum entries: 20
ttl string optional

Go duration from zero through 8760h. Empty or zero uses the service default.

List your form targets

GET/api/v1/forms

mTLS 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
StatusMeaning
401Client certificate required or expired (unauthorized)
403Certificate 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
token string required

Public form token — POST target is /f/{token}

name string required
from string required
to string[] required
subject string required
redirect_url string optional
allowed_origins string[] optional
rate_limit integer required
cc_submitter boolean required
field_labels object optional
enabled boolean required
created_at string required
Format: date-time
cert_serial string optional

Serial of the client certificate that authorized this form; submissions are refused once that certificate is revoked

FormUploads
max_files integer optional

Files per submission, 1-10 (0 = uploads off)

Default: 0 · Minimum: 0 · Maximum: 10
max_bytes integer optional

Per-file size cap in bytes (0 = 10 MiB; max 1 GiB)

Default: 10485760 · Minimum: 0 · Maximum: 1073741824
content_types string[] optional

Bare media types such as application/pdf (max 20; empty = any)

Maximum entries: 20
ttl string optional

Go duration from zero through 8760h. Empty or zero uses the service default.

Get one form target

GET/api/v1/forms/{token}

mTLS client certificate

Read one form target. Foreign and missing tokens both return 404.

Path parameters

token string required

Request body: none.

Success response

200 OK — Form target

application/json: FormResponse

Errors and retry behavior
StatusMeaning
404Unknown token, or owned by another client
401Client certificate required or expired (unauthorized)
403Certificate 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
token string required

Public form token — POST target is /f/{token}

name string required
from string required
to string[] required
subject string required
redirect_url string optional
allowed_origins string[] optional
rate_limit integer required
cc_submitter boolean required
field_labels object optional
enabled boolean required
created_at string required
Format: date-time
cert_serial string optional

Serial of the client certificate that authorized this form; submissions are refused once that certificate is revoked

FormUploads
max_files integer optional

Files per submission, 1-10 (0 = uploads off)

Default: 0 · Minimum: 0 · Maximum: 10
max_bytes integer optional

Per-file size cap in bytes (0 = 10 MiB; max 1 GiB)

Default: 10485760 · Minimum: 0 · Maximum: 1073741824
content_types string[] optional

Bare media types such as application/pdf (max 20; empty = any)

Maximum entries: 20
ttl string optional

Go duration from zero through 8760h. Empty or zero uses the service default.

Partially update a form target

PATCH/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

token string required

Request body

name string optional

Human label, shown as the heading of submission emails Maximum 200 UTF-8 bytes.

Minimum length: 1
to string[] optional

Recipients of submission emails

Minimum entries: 1
subject string optional

Default subject (submitters can override via _subject) Maximum 255 UTF-8 bytes.

Minimum length: 1
redirect_url string optional

Post-submit redirect for browser form posts Maximum 2048 UTF-8 bytes.

Format: uri
allowed_origins string[] optional

Origins 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: 20
rate_limit integer optional

Submissions/hour for this form, 0-10000 (0 = service default)

Minimum: 0 · Maximum: 10000
cc_submitter boolean optional

CC 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_labels object optional

Map submitted field names to display labels. At most 64 entries; labels are at most 200 UTF-8 bytes.

enabled boolean optional

Enable or disable this form.

Success response

200 OK — Updated form target

application/json: FormResponse

Errors and retry behavior
StatusMeaning
400Invalid request, or a required field (name/subject/to) was cleared
404Unknown token, or owned by another client
413Request body exceeds the maximum size
422Invalid address, origin, redirect URL, rate limit (0-10000), or field length
401Client certificate required or expired (unauthorized)
403Certificate 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
token string required

Public form token — POST target is /f/{token}

name string required
from string required
to string[] required
subject string required
redirect_url string optional
allowed_origins string[] optional
rate_limit integer required
cc_submitter boolean required
field_labels object optional
enabled boolean required
created_at string required
Format: date-time
cert_serial string optional

Serial of the client certificate that authorized this form; submissions are refused once that certificate is revoked

FormUploads
max_files integer optional

Files per submission, 1-10 (0 = uploads off)

Default: 0 · Minimum: 0 · Maximum: 10
max_bytes integer optional

Per-file size cap in bytes (0 = 10 MiB; max 1 GiB)

Default: 10485760 · Minimum: 0 · Maximum: 1073741824
content_types string[] optional

Bare media types such as application/pdf (max 20; empty = any)

Maximum entries: 20
ttl string optional

Go duration from zero through 8760h. Empty or zero uses the service default.

Delete a form target

DELETE/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

token string required

Request body: none.

Success response

200 OK — Deleted

deleted boolean required
Value: true
token string required

application/json: object

Errors and retry behavior
StatusMeaning
404Unknown token, or owned by another client
401Client certificate required or expired (unauthorized)
403Certificate or client identity rejected (cert_invalid)

List a form's persisted submissions

GET/api/v1/forms/{token}/submissions

mTLS 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

token string required

Query parameters

before string optional

Keyset cursor — the id of the last row from a previous page. Ignored with format=csv.

limit integer optional

Page size, default 50, capped at 100. Ignored with format=csv.

Default: 50 · Minimum: 1 · Maximum: 100
format string optional

Case-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
StatusMeaning
400Unparsable limit
404Unknown token, or owned by another client
401Client certificate required or expired (unauthorized)
403Certificate 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
submissions FormSubmissionResponse[] required
count integer required
next_before string optional

Cursor for the next page; present only when this page was full

Get one persisted submission

GET/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

token string required
id string required

Request body: none.

Success response

200 OK — Submission

application/json: FormSubmissionResponse

Errors and retry behavior
StatusMeaning
404Unknown id, or belonging to a different form
401Client certificate required or expired (unauthorized)
403Certificate 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
id string required
form_token string required
form_name string required

Snapshot of the form's name at submission time

message_id string required

The outbound message this submission produced

fields object[] required

Submitted (name, value) pairs, in submission order

Item fields
name string required
value string required
truncated boolean required

True when a field value was capped (total name+value bytes over 16KiB); the field name is always kept whole

subject string required
reply_to string required
source_ip string required
user_agent string required

Capped at 128 bytes

origin string required

The submitting request's Origin header, verbatim

spam_score integer | null required

Null when never classified (captcha off, or a solved challenge, which skips re-classification)

spam_reasons string[] | null required
outcome string required
Values: "clean", "challenge_solved", "unscored"
attachments object[] optional

The 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
id string required

depot file id

name string required

Filename as depot recorded it, capped at 255 bytes

size integer required
Format: int64
type string optional

depot's parsed media type

url string optional

depot download link

created_at string required
Format: date-time

Submit an HTML form

POST/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

token string required

Request body

_replyto string optional

Reply email address; invalid values are ignored.

email string optional

Ordinary content field and fallback reply address.

_subject string optional

Subject override; CR/LF is rejected.

_redirect string optional

Allowed success redirect override.

_gotcha string optional

Honeypot: leave empty.

_challenge string optional

CAPTCHA nonce returned by challenge_required.

cf-turnstile-response string optional

CAPTCHA widget token returned after solving.

_attachment string[] optional

Repeat 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
StatusMeaning
403The origin is not allowed, or a JSON caller needs CAPTCHA verification (challenge_required).
404Unknown or disabled form token
413Request body or rendered message exceeds the maximum size
415Content-Type is not urlencoded or multipart form data
422Invalid submission (e.g. line breaks in _subject, too many fields)
429Retry-After gives the wait in seconds.
503The form's From domain is paused because its ownership TXT record is missing (error code "domain_paused"); Retry-After is 300.
400Malformed 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
ok boolean required
Value: true
id string required

Mint a depot upload grant for a form

POST/f/{token}/upload-grant

Public · 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

token string required

Header parameters

Origin string optional

Page origin. A usable Referer-derived origin is accepted when Origin is absent or null.

Referer string optional

Fallback source of the page origin.

Request body: none.

Success response

201 Created — Grant minted

application/json: UploadGrantResponse

Errors and retry behavior
StatusMeaning
400origin_required — no usable Origin or Referer on the request
403Origin not permitted for this form
404Unknown or disabled form token
422uploads_not_enabled — the form has no upload policy
429Retry-After gives the wait in seconds.
503depot_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_url string required
Format: uri
expires_at string required
Format: date-time
max_files integer required
max_bytes integer required
content_types string[] optional
file_ttl string optional

Go duration string, echoing what was sent to depot; omitted when not set

Get webhook signing public keys

GET/.well-known/jwks.json

Public · 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
StatusMeaning
429Retry-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
keys PublicJWK[] required

Inspect your client certificate

GET/who

mTLS 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

Accept string required

Selects 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
StatusMeaning
401JSON 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_id string required
senders string[] required
webhooks string[] required
valid boolean required
key_type string required
not_before string required
Format: date-time
not_after string required
Format: date-time
expires_in_days integer required

Whole days until expiry, truncated toward zero; recently expired certificates can still read 0.

renew_recommended boolean required

True when the certificate is inside the service renewal window, including expired certificates.

serial string required
revoked boolean required
reasons string[] required
webhook_signing_enabled boolean required
webhook_signing_key_id string optional

Inspect any certificate

POST/who

Public · 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
StatusMeaning
400Empty, 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_id string required
senders string[] required
webhooks string[] required
key_type string required
not_before string required
Format: date-time
not_after string required
Format: date-time
expires_in_days integer required

Whole days until expiry, truncated toward zero; recently expired certificates can still read 0.

renew_recommended boolean required

True when the certificate is inside the service renewal window, including expired certificates.

serial string required
reasons string[] required
webhook_signing_enabled boolean required
webhook_signing_key_id string optional
WhoResponse
client_id string required
senders string[] required
webhooks string[] required
valid boolean required
key_type string required
not_before string required
Format: date-time
not_after string required
Format: date-time
expires_in_days integer required

Whole days until expiry, truncated toward zero; recently expired certificates can still read 0.

renew_recommended boolean required

True when the certificate is inside the service renewal window, including expired certificates.

serial string required
revoked boolean required
reasons string[] required
webhook_signing_enabled boolean required
webhook_signing_key_id string optional

Renew your client certificate

POST/api/v1/certs/renew

mTLS 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_pem string required

PEM-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
StatusMeaning
400Malformed JSON, missing or invalid CSR, an unsupported key, or a CSR reusing the current certificate key.
403The 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")
413Request body exceeds the maximum size (error code "request_too_large")
429Retry-After gives the wait in seconds.
503Certificate renewal is not configured (error code "unavailable")
500Certificate renewal failed
401Client 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_pem string required

The new, PEM-encoded certificate. Never a private key.

serial string required

New certificate's serial, lowercase hex

not_after string required
Format: date-time
previous_serial string required

Serial of the certificate presented for the request (mTLS)

active_certs integer required

The client's active certificate count after this renewal (at most 2)

Renew an already-expired certificate

POST/certs/renew

Public · 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_pem string required

PEM-encoded, already-expired certificate to renew

Minimum length: 1
csr_pem string required

PEM-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
StatusMeaning
400Malformed input or a uniformly refused certificate, expiry, sender ownership, or key proof.
413Request body exceeds the maximum size (error code "request_too_large")
429Retry-After gives the wait in seconds.
503Certificate renewal is not configured (error code "unavailable")
500Certificate renewal failed

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

CertRenewResponse
cert_pem string required

The new, PEM-encoded certificate. Never a private key.

serial string required

New certificate's serial, lowercase hex

not_after string required
Format: date-time
previous_serial string required

Serial of the certificate presented for the request (mTLS)

active_certs integer required

The client's active certificate count after this renewal (at most 2)

Send a test email

POST/api/v1/test

mTLS 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

to string required

One email address, optionally with a display name.

Minimum length: 1

Success response

202 Accepted — Test message queued

application/json: TestSendResponse

Errors and retry behavior
StatusMeaning
400Missing to, malformed JSON, wrong Content-Type, or no certificate email SAN
401Client certificate required
403Client certificate validation failed
422Invalid address or suppressed recipient
429Retry-After gives the wait in seconds.
500Message could not be queued

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

TestSendResponse
id string required
from string required
to string required
status string required
Values: "queued"

Poll for a test email reply

GET/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_id string 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
StatusMeaning
401Client certificate required
404Unknown, foreign, expired-tracker, or non-test message
500Reply lookup failed
403Certificate 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
from string required
subject string required
body string required

Reply body capped at 4000 bytes.

received_at string required
Format: date-time

Legacy alias for POST /api/v1/send

POST/v1/send

mTLS 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
StatusMeaning
400Invalid request
403Sender not authorized by certificate
413Request too large (error codes "message_too_large", or "attachment_too_large" when depot refuses a files[] entry).
422Unprocessable 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").
503Temporarily unavailable.
429Retry-After gives the wait in seconds.
401Client certificate required or expired (unauthorized)

Field and response shapes

Expand a linked shape to inspect its field types. Response examples show selected fields.

SendResponse
id string required

Message ID (ULID)

request_id string required

Echoed from request

recipients integer required

Number of recipients queued

status string required

queued 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

OPTIONS/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

token string required

Header parameters

Origin string 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

OPTIONS/f/{token}/upload-grant

Public · 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

token string required

Header parameters

Origin string 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

MethodPurpose
POST /api/v1/emails/checkCheck an email address
POST /api/v1/email-verificationsCreate an ownership verification
POST /api/v1/email-verifications/{id}/confirmConfirm mailbox ownership
GET /api/v1/email-verifications/{id}Get an ownership verification

Check an email address

POST/api/v1/emails/check

mTLS 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

email string required

Response

Schema: EmailCheckResult. See OpenAPI for complete field types and enums.

Errors and retry behavior
StatusMeaning
400Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code
401Client certificate required or expired
403Client identity rejected or sender_not_authorized
413JSON request exceeds 4096 bytes
429rate_limited; Retry-After gives a wait in seconds
503feature_disabled, domain_paused, or unavailable infrastructure

Create an ownership verification

POST/api/v1/email-verifications

mTLS 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

email string required
from string required
Authorized certificate sender
purpose string required
subject_id string required
request_id string required

Response

Schema: EmailVerificationResponse. See OpenAPI for complete field types and enums.

Errors and retry behavior
StatusMeaning
400Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code
401Client certificate required or expired
403Client identity rejected or sender_not_authorized
413JSON request exceeds 4096 bytes
422recipient_suppressed for this client
429rate_limited; Retry-After gives a wait in seconds
503feature_disabled, domain_paused, or unavailable infrastructure
409request_conflict: request_id already used with different fields

Confirm mailbox ownership

POST/api/v1/email-verifications/{id}/confirm

mTLS 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

code string required

Response

Schema: EmailVerificationResponse. See OpenAPI for complete field types and enums.

Errors and retry behavior
StatusMeaning
400Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code
401Client certificate required or expired
403Client identity rejected or sender_not_authorized
413JSON request exceeds 4096 bytes
429rate_limited; Retry-After gives a wait in seconds
503feature_disabled, domain_paused, or unavailable infrastructure
404Challenge missing or owned by another client

Get an ownership verification

GET/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
StatusMeaning
400Invalid JSON or address, unsupported_address, unroutable_address, or invalid_code
401Client certificate required or expired
403Client identity rejected or sender_not_authorized
413JSON request exceeds 4096 bytes
429rate_limited; Retry-After gives a wait in seconds
503feature_disabled, domain_paused, or unavailable infrastructure
404Challenge missing or owned by another client