How AI agents send and receive email via rail. Authentication is mTLS client certificates — no API keys, no OAuth, no shared secrets. Authenticated API requests recheck certificate expiry on persistent connections and return HTTP 401
unauthorized after expiry. Client dashboard accounts can use optional passkeys; API and SMTP authentication still require mTLS certificates. See also:
API docs ·
OpenAPI spec ·
ai-plugin.json
Opt-in browser signup requires initial admin approval and domain ownership proof. Managed credentials also require durable enrollment and activated sender ownership during renewal.
Keep the ownership TXT record published. Rail checks it hourly. Two confirmed missing-proof checks pause only that domain. A send from it returns HTTP 503 with domain_paused and Retry-After: 300. Other domains of the account keep working. Browser login remains available to restore proof. Admin approval is retained.
Sending Email — HTTP API (recommended)
POST /api/v1/send (mTLS required)
curl -s --cert my-agent.crt --key my-agent.key \
https://smtp.ataca.io/api/v1/send \
-H "Content-Type: application/json" \
-d '{
"request_id": "send-example-1",
"from": "agent@smtp.ataca.io",
"to": ["user@example.com"],
"subject": "Task complete",
"body_text": "Your report is ready.",
"body_html": "<p>Your report is <b>ready</b>.</p>"
}'
# Response (202; accepted request replay: 200):
{"id": "01jx...", "request_id": "send-example-1", "recipients": 1, "status": "queued"}
Required: request_id, from, to, subject, and nonempty body_text or body_html.
Optional fields
| Field | Purpose |
cc | CC recipients (array) |
reply_to | Override Reply-To (disables VERP tracking) |
unsubscribe_url | Injects List-Unsubscribe per RFC 8058 |
attachments | Depot file ids from POST /api/v1/upload-grants (max 20), resolved to download links; requires depot to be configured. An accepted send keeps each attached file for at least depot's default retention |
files | Inline files, each {filename, content_type, content} with required filename and nonempty padded base64 content. Optional content_type defaults to application/octet-stream. Counts with attachments toward the limit of 20. Requires smtp.attachments.enabled and depot. The call waits for upload and scan; a retry with the same request_id uploads nothing. Errors: attachment_too_large (413), attachment_rejected (422) |
Sending attachments — POST /api/v1/upload-grants (mTLS required)
# Depot scopes an upload to the certificate that made it, so a file you
# upload yourself is invisible to rail. Mint a grant on rail's identity first.
# Also requires depot's own grants.enabled (and the scan.enabled it needs).
curl -s --cert my-agent.crt --key my-agent.key \
https://smtp.ataca.io/api/v1/upload-grants \
-H "Content-Type: application/json" -d '{"max_bytes": 10485760}'
# Response (201): {"upload_url": "https://depot.ataca.io/u/<token>", "expires_at": "...", "max_files": 1, "max_bytes": 10485760}
# Upload before the grant expires (15 minutes); no certificate needed here.
curl -s -X POST "$UPLOAD_URL?filename=report.pdf" \
-H "Content-Type: application/pdf" --data-binary @report.pdf
# Response: {"id": "f_123"} -- pass this id in "attachments" on /api/v1/send
Python
import requests
resp = requests.post(
"https://smtp.ataca.io/api/v1/send",
cert=("my-agent.crt", "my-agent.key"),
verify="ca.crt",
json={
"request_id": "send-example-1",
"from": "agent@smtp.ataca.io",
"to": ["user@example.com"],
"subject": "Task complete",
"body_text": "Your report is ready.",
},
)
resp.raise_for_status()
print(resp.json()) # {"id": "01jx...", "recipients": 1, "status": "queued"}
Node.js
import { readFileSync } from "fs";
import https from "https";
const resp = await fetch("https://smtp.ataca.io/api/v1/send", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
request_id: "send-example-1",
from: "agent@smtp.ataca.io",
to: ["user@example.com"],
subject: "Task complete",
body_text: "Your report is ready.",
}),
agent: new https.Agent({
cert: readFileSync("my-agent.crt"),
key: readFileSync("my-agent.key"),
ca: readFileSync("ca.crt"),
}),
});
console.log(await resp.json());
Go
cert, _ := tls.LoadX509KeyPair("my-agent.crt", "my-agent.key")
caPEM, _ := os.ReadFile("ca.crt")
pool := x509.NewCertPool()
pool.AppendCertsFromPEM(caPEM)
client := &http.Client{Transport: &http.Transport{
TLSClientConfig: &tls.Config{
Certificates: []tls.Certificate{cert},
RootCAs: pool,
},
}}
body := `{"request_id":"send-example-1","from":"agent@smtp.ataca.io","to":["user@example.com"],` +
`"subject":"Task complete","body_text":"Your report is ready."}`
resp, _ := client.Post("https://smtp.ataca.io/api/v1/send",
"application/json", strings.NewReader(body))
Receiving Email
How it works
Sender → internet MTA → rail :25 (STARTTLS) → local domain check → HTTP POST to your webhook
Webhook payload (inbound)
{
"type": "inbound",
"message_id": "01jx...",
"from": "user@example.com",
"to": ["agent@smtp.ataca.io"],
"subject": "Re: Task complete",
"raw_message": "<base64-encoded RFC 5322 message>",
"received_at": "2025-01-15T10:30:00Z"
}
// On a domain with attachment stripping enabled (rail domains attachments --strip),
// raw_message loses its attachment parts and a "files" array lists them instead:
// [{id, name, size, content_type, status: "clean"|"infected"|"skipped", url}]. See docs/webhooks.md#attachments.
Webhook payload (reply — VERP tracked)
{
"type": "reply",
"message_id": "01jy...",
"in_reply_to": "01jx...", // original message ID
"from": "user@example.com",
"to": ["agent@smtp.ataca.io"],
"subject": "Re: Task complete",
"raw_message": "<base64>",
"received_at": "2025-01-15T10:30:00Z",
"original_sender": "agent@smtp.ataca.io",
"original_recipients": ["user@example.com"]
}
Webhook payload (bounce — hard bounce of a sent message)
{
"type": "bounce",
"message_id": "01jx...", // the ORIGINAL message that bounced
"received_at": "2025-01-15T10:30:00Z",
"original_message_id": "01jw...",
"bounced_recipient": "user@example.com",
"bounce_status": "5.1.1",
"bounce_diagnostic": "smtp; 550 5.1.1 User unknown",
"bounce_type": "hard"
}
// Only hard (5.x.x) bounces fire a webhook; the recipient is also auto-suppressed.
// Soft bounces are retried by rail and send no webhook.
Webhook payload (complaint — verified spam complaint against a sent message)
{
"type": "complaint",
"message_id": "01jx...", // unique id for this complaint event
"received_at": "2025-01-15T10:30:00Z",
"original_message_id": "01jw...",
"complained_recipient": "user@example.com",
"feedback_type": "abuse",
"complaint_source": "arf"
}
// Fires when an ARF feedback report to rail's abuse address MAC-verifies against
// the message's VERP tags; the recipient is also auto-suppressed. Unverified reports
// and plain abuse mail are recorded for review only, with no webhook.
Python receiver (Flask)
from flask import Flask, request
app = Flask(__name__)
@app.route("/hooks/email", methods=["POST"])
def receive_email():
payload = request.json
print(f"From: {payload['from']}, Subject: {payload['subject']}")
if payload["type"] == "reply":
print(f"Reply to: {payload['in_reply_to']}")
elif payload["type"] == "bounce":
print(f"Bounced: {payload['bounced_recipient']} ({payload['bounce_status']})")
elif payload["type"] == "complaint":
print(f"Complaint: {payload['complained_recipient']} ({payload['feedback_type']})")
return "", 200 # 2xx acknowledges; 4xx is permanent; 5xx retries within the configured limit
Node.js receiver (Express)
import express from "express";
const app = express();
app.use(express.json());
app.post("/hooks/email", (req, res) => {
const { type, from, subject, in_reply_to } = req.body;
console.log(`From: ${from}, Subject: ${subject}`);
if (type === "reply") console.log(`Reply to: ${in_reply_to}`);
res.sendStatus(200);
});
app.listen(3000);
Checking Delivery Status
GET /api/v1/messages — your own messages
curl -s --cert my-agent.crt --key my-agent.key \
"https://smtp.ataca.io/api/v1/messages?status=bounced&limit=20"
# Newest first, scoped to your certificate's CN. Filters: status, sender,
# recipient, since, until. Page with ?before=<next_before>.
# Each row's attachments counts the files the message carried.
# open_summary (present once opened) breaks opens down by classification.
GET /api/v1/messages/{id} — one message
curl -s --cert my-agent.crt --key my-agent.key \
https://smtp.ataca.io/api/v1/messages/01jx...
# A list row plus updated_at; attachments is a list of
# {filename, content_type, size, verdict}. No depot id or URL.
GET /api/v1/messages/{id}/deliveries — one message
curl -s --cert my-agent.crt --key my-agent.key \
https://smtp.ataca.io/api/v1/messages/01jx.../deliveries
# Returns every envelope recipient's outcome: pending, delivered, bounced,
# or untracked (no delivery record — carries a note and attempts: 0)
Renewing Your Certificate
GET /who — when to renew
# expires_in_days counts whole days to expiry, truncated toward zero.
# renew_recommended turns true inside pki.renew_window, 30 days by default.
# rail also mails your contact address 7 and 1 days before expiry.
POST /api/v1/certs/renew — CSR for a new key, never a key
openssl genpkey -algorithm ed25519 -out new.key
openssl req -new -key new.key -subj /CN=my-agent -out r.csr
jq -Rs '{csr_pem: .}' r.csr | curl --cert my-agent.crt --key my-agent.key \
-H 'Content-Type: application/json' -d @- https://smtp.ataca.io/api/v1/certs/renew
# → 200 {"cert_pem":"...","serial":"...","not_after":"...","previous_serial":"...","active_certs":2}
# CN, email SANs and webhook URI SANs are copied onto the new cert unchanged.
# The CSR must carry a new key (400 invalid_request if it reuses the old one).
# The presented cert must be your current one (403 renew_not_current if not),
# the client must not be disabled (403 cert_invalid), and it must be at least
# pki.renew_min_interval old, default 24h (429 renew_too_soon, Retry-After
# set). You hold at most two active certs; a third supersedes the oldest,
# same as `rail certs issue|sign`.
Form Submissions (public endpoint)
POST /f/{token} (no client certificate; opt-in)
# Operator creates a form target bound to your client:
rail forms create --client my-agent --name contact \
--from noreply@smtp.ataca.io --to you@example.com \
--subject "Contact form" --redirect https://example.com/thanks
# → token 01jx… ; any static page can then post to /f/01jx…
# Default: 3 submissions/hour/IP across all forms and clients; IPv6 shares /64.
# Over quota: 429 rate_limited with Retry-After. Counters reset on restart.
# Challenges do not consume quota; verified solves do.
# Clear SQL injection and XSS probes require CAPTCHA when configured.
Client domains and forwarding (mTLS required)
Use GET/POST /api/v1/domains to list or register your domains.
Registration accepts {"domain":"example.net"} and reserves a pending name with receiving disabled.
The certificate CN owns it. Foreign and missing domains return 404.
Use GET/PATCH/DELETE /api/v1/domains/{domain} for status, routing, and release.
PATCH accepts webhook_urls, mailboxes, receiving_enabled, and dns_mode.
Arrays replace their previous values. Revoke certificate references before release.
Expired, unrevoked certificates on disk can still reserve the domain.
Read DNS guidance from GET /api/v1/domains/{domain}/records.
Its response includes domain, dns_mode, receiving_enabled, and records.
Records include purpose and requirement alongside name, type, and value.
MX appears only when receiving is enabled. SPF and DMARC values are recommended examples.
Merge SPF authorization with existing providers and preserve valid DMARC policies and report destinations.
Publish ownership proof and DKIM keys, then call POST /api/v1/domains/{domain}/verify.
Keep receiving disabled for externally hosted mailboxes. Enable it with a webhook or enabled forward when needed.
Keep the ownership TXT published. Two hourly missing observations pause only that domain by default.
Restoring the original TXT resumes it; domain_checks controls the check policy.
Call POST /api/v1/domains/{domain}/check without a body for read-only DNS diagnostics.
The response contains domain, dns_mode, receiving_enabled, checked_at, and results.
Results contain check, subject, and status, plus optional observed, want, and detail.
Statuses are pass, warn, fail, skip, or error.
Sending-only domains skip MX. SPF accepts combined providers, DMARC accepts valid custom policies, and DKIM compares parsed keys.
DNS errors appear within a 200 response. Checks finish within 20 seconds and never change ownership state or counters.
Passing diagnostics neither activates a pending domain nor guarantees delivery. Use /verify to record ownership evidence.
Delegated DNS is opt-in. Set dns_mode to delegated on registration or PATCH.
Configure both returned nameservers at your registrar, then verify.
Friendly character-name pairs belong permanently to one registration generation.
Delegated responses omit ownership_record; GET /records returns NS records.
Rail checks parent delegation and hosts mail DNS after verification. It adds no client apex A/AAAA records.
Changing mode rotates proof and pauses previously verified domains until the new proof verifies.
Returning to records requires external DNS and the new TXT proof.
Use GET/POST /api/v1/domains/{domain}/forwards to list or create forwarding rules.
Creation accepts local_part, destination, and optional from_munging.
Use PATCH/DELETE /api/v1/domains/{domain}/forwards/{local_part}/{destination} for one rule.
URL-encode each path segment. PATCH accepts enabled and from_munging.
Re-enabling clears hard-bounce suppression; complaint and manual suppressions remain.
Lists return domains or forwards, plus next_cursor when more remain.
Pass it as after; limit accepts 1–100, default 100.
Creation quotas are 100 domains per client and 1,000 forwards per domain.
Registration, verification, DNS checks, and DNS-mode changes share 10 requests per minute per client.
JSON bodies are limited to 64 KiB. Routing allows 20 webhooks and 1,000 mailboxes.
Unknown fields are rejected. Responses contain public DNS records, never private DKIM keys.
See OpenAPI for request and response schemas.
Self-serve over mTLS — POST /api/v1/forms
curl --cert my-agent.crt --key my-agent.key \
-X POST https://smtp.ataca.io/api/v1/forms -H 'Content-Type: application/json' \
-d '{"name":"contact","from":"noreply@smtp.ataca.io","to":["you@example.com"],"subject":"Contact form"}'
# → 201 {"token":"01jx…", …}. GET /api/v1/forms lists yours;
# GET/PATCH/DELETE /api/v1/forms/{token} manage one (another client's token is 404).
# "cc_submitter": true (CLI: --cc-submitter) CC's the submitter a copy —
# rate-limited per address across all forms, suppression-checked.
# "field_labels": {"first_name":"First Name"} (CLI: repeatable --label
# name=Label) sets display labels; unlisted fields auto-prettify.
# "uploads": {"max_files":3,"max_bytes":10485760,"content_types":["application/pdf"],"ttl":"168h"}
# accepts files via depot: the page POSTs /f/{token}/upload-grant, uploads to
# the returned upload_url, and submits the ids as _attachment fields. rail
# links only files depot reports clean; a file part in the post is 422.
# Spam-likely posts may answer 403 challenge_required (Turnstile site_key +
# nonce): render the widget, re-POST with _challenge + cf-turnstile-response.
Partial update — PATCH /api/v1/forms/{token}
curl --cert my-agent.crt --key my-agent.key \
-X PATCH https://smtp.ataca.io/api/v1/forms/01jx… -H 'Content-Type: application/json' \
-d '{"rate_limit":60,"enabled":false}'
# → 200 {"token":"01jx…", "rate_limit":60, "enabled":false, …}
# Send only the fields to change: an absent key keeps the current value,
# an explicit ""/[]/{} clears it. from/token/client are immutable and
# ignored if sent -- from stays bound to the cert that created the form.
HTML embed
<form action="https://smtp.ataca.io/f/01jx…" method="POST">
<input name="name"><input name="email"><textarea name="message"></textarea>
<input name="_gotcha" style="display:none"> <!-- honeypot: keep empty -->
<button>Send</button>
</form>
| Special field | Effect |
_replyto | Reply-To (falls back to a field named email) |
_subject | Subject override (line breaks rejected) |
_redirect | Redirect override — origin-allowlisted only |
_gotcha | Honeypot — a filled value drops the submission |
Reviewing submissions — GET /api/v1/forms/{token}/submissions
curl --cert my-agent.crt --key my-agent.key \
https://smtp.ataca.io/api/v1/forms/01jx…/submissions
# → 200 {"submissions":[{"id":"01k…","fields":[…],"outcome":"clean",…}],"count":1}
# Every ACCEPTED submission is persisted (honeypot/challenged/rate-limited/
# all-suppressed ones never are). Newest-first; ?before=<id> pages (keyset,
# next_before in the response), ?limit= default 50, max 100.
# GET .../submissions/{id} fetches one. Both are owner-scoped like the form
# target itself — a token or id you don't own answers 404.
# ?format=csv (or Accept: text/csv) streams every submission as CSV instead:
# id,received_at,outcome,source_ip,user_agent,origin,subject,reply_to, then
# one column per field name. UTF-8 BOM + CRLF; every cell is OWASP-guarded
# against CSV injection (a leading =/+/-/@/tab/CR gets a "'" prefix).