agent integration
Operational
Agent Integration Guide
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.

Setup
rail certs issue \
  --name my-agent \
  --email agent@smtp.ataca.io \
  --webhook https://my-agent.example.com/hooks/email
FieldMeaning
CNAgent identity — appears in logs, rate-limit buckets
Email SANsAddresses the agent is allowed to send as
URI SANsWebhook URLs where inbound mail is POSTed
Sending Email — HTTP API (recommended)
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.

FieldPurpose
ccCC recipients (array)
reply_toOverride Reply-To (disables VERP tracking)
unsubscribe_urlInjects List-Unsubscribe per RFC 8058
attachmentsDepot 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
filesInline 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)
# 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
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"}
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());
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))
Sending Email — SMTP (port 465)
import smtplib, ssl
from email.message import EmailMessage
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
ctx.load_cert_chain("my-agent.crt", "my-agent.key")
ctx.load_verify_locations("ca.crt")
msg = EmailMessage()
msg["From"] = "agent@smtp.ataca.io"
msg["To"] = "user@example.com"
msg["Subject"] = "Task complete"
msg.set_content("Your report is ready.")
with smtplib.SMTP_SSL("smtp.ataca.io", 465, context=ctx) as smtp:
  smtp.send_message(msg)
Receiving Email
Sender → internet MTA → rail :25 (STARTTLS) → local domain check → HTTP POST to your webhook
{
  "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.
{
  "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"]
}
{
  "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.
{
  "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.
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
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);
Reply Tracking (VERP)
# When your agent sends without setting reply_to, rail injects:
Reply-To: reply+<msg_id>.<hmac>@smtp.ataca.io
# When the recipient replies:
# 1. Rail receives the reply on :25
# 2. Matches it to the original message via the signed tag
# 3. Delivers to your webhook with type:"reply" and in_reply_to set
# To disable tracking for a specific message, set reply_to explicitly:
{"reply_to": "support@example.com", ...}
Checking Delivery Status
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.
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.
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
# 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.
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`.
Client testing and webhook keys

POST /api/v1/test requires mTLS and JSON {"to":"recipient@example.com"}. It returns HTTP 202 with id, from, to, and status. The sender is the first certificate email SAN. Limits include five tests per hour per client/source-IP pair.

GET /api/v1/test/reply/{msg_id} requires mTLS. HTTP 204 means no reply; HTTP 200 returns from, subject, body, and received_at. Tracker state lasts approximately one hour and resets on restart.

GET /api/v1/messages/{id}/opens returns owned open events and classification counts, even when tracking is disabled.

GET /.well-known/jwks.json publishes webhook signing public keys without authentication. Signing-disabled services return {"keys":[]}.

GET /who needs Accept: application/json for JSON. Anonymous POST /who returns metadata without valid or revoked. Renewal JSON bodies fit 64 KiB and reject unknown fields.

Renewing an Already-Expired Certificate
# Port 443 rejects an expired client cert at the TLS handshake, so use this
# route instead. cert_pem is your expired certificate; csr_pem's key must
# match cert_pem's key (the opposite of /api/v1/certs/renew) -- that match
# is your only proof of identity here. Must be within pki.renew_grace of
# expiry, default 168h/7 days.
jq -n --rawfile c old.crt --rawfile r r.csr '{cert_pem:$c, csr_pem:$r}' \
  | curl -H 'Content-Type: application/json' -d @- https://smtp.ataca.io/certs/renew
# Every policy or proof refusal (bad key match, wrong CA, revoked, disabled, outside the
# grace window, not actually expired) answers identically: 400
# invalid_request "certificate and CSR do not match or the certificate
# cannot be renewed". Only a too-frequent renewal gets its own 429
# renew_too_soon, reachable only after that proof. Service failures return 500 or 503.
Form Submissions (public endpoint)
# 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.

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.

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.
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.
<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 fieldEffect
_replytoReply-To (falls back to a field named email)
_subjectSubject override (line breaks rejected)
_redirectRedirect override — origin-allowlisted only
_gotchaHoneypot — a filled value drops the submission
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).
Best Practices
#Practice
1Use the HTTP API — simpler than SMTP, better error reporting, JSON native
2Check HTTP response status. 202 means queued; 200 replays an accepted request. Retry timeouts, 429, and temporary 5xx responses with the same request ID and payload. Honor Retry-After and bound retries. Fix other 4xx errors before retrying. Restore domain ownership proof before retrying 503 domain_paused. SMTP uses different classes: 4xx is temporary, and 5xx is permanent. See Send email.
3Include both body_text and body_html for maximum mail client compatibility. Text-only API sends get an auto-generated HTML alternative; SMTP submissions too when smtp.auto_multipart is enabled
4Handle webhook retries. Return 2xx promptly after durable acceptance. Incoming webhook 4xx responses stop retries. rail retries 5xx and transport failures every five minutes, within the configured attempt limit.
5Use request_id for idempotent retries on the send side
6Add unsubscribe_url for user-facing mail (required by Gmail/Yahoo)
7Don't send bulk marketing — rail is for transactional mail only
API Discovery
EndpointFormatPurpose
/openapi.yamlOpenAPI 3.1Machine-readable API spec
/.well-known/ai-plugin.jsonJSONAI agent plugin manifest
/llms.txtPlain textLLM-readable service summary

Email checks and ownership verification

Enable email_checks and use an operational mTLS client certificate. POST /api/v1/emails/check accepts {"email":"person@example.com"} and returns routing, domain classification, SMTP evidence, and validity freshness.

Results are valid, invalid, undeliverable, or unknown. MX/A/AAAA queries share bounded caches. Every attempted SMTP check has a durable 24-hour cooldown. Successful delivery evidence remains fresh for 30 days.

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.

Domain categories include business, free, paid, disposable, privacy relay, education, government, nonprofit, custom, and unknown. Classification does not automatically block sending. Single-use and temporary behavior remain separate nullable traits.

A configured local index imports Disposable’s GitHub provider registry and normal disposable feed. It checks on startup and every six hours. Updates are transactional and preserve the last successful data on failure. Indexed results include the source URL and dataset content digest. Unmatched domains use inferred business, independently of DNS or SMTP 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 lookups only.

POST /api/v1/email-verifications accepts email, authorized from, purpose, subject_id, and request_id. It queues a six-digit code with ten-minute expiry and five failed attempts. POST /api/v1/email-verifications/{id}/confirm accepts code. GET /api/v1/email-verifications/{id} reads its status. Replaying an accepted request_id sends nothing. Foreign and missing challenges both return 404.

Ownership verification belongs to one client, address, purpose, and subject. Opens do not confirm ownership; proxy activity is indeterminate. See the integration guide and OpenAPI schemas.