# rail

> Transactional email server with mTLS authentication

rail is a pure-Go email server for service-to-service transactional email
(notifications, alerts, receipts). Not for bulk marketing.

## Auth

mTLS client certificates. No API keys. The certificate encodes:
- CN: client identity
- Email SANs: allowed sender addresses
- URI SANs: webhook URLs for inbound delivery

## Send email

POST /api/v1/send (mTLS required)

```json
{
  "from": "agent@smtp.ataca.io",
  "to": ["user@example.com"],
  "subject": "Hello",
  "body_text": "Plain text body",
  "body_html": "<p>HTML body</p>"
}
```

Response: `{"id": "01jx...", "recipients": 1, "status": "queued"}`

Optional fields: request_id, cc, reply_to, unsubscribe_url, body_html.

Also accepts SMTP on port 465 (implicit TLS, same mTLS cert).

## Receive email

Inbound mail to local domains is POSTed to webhook URLs as JSON:

```json
{
  "type": "inbound",
  "message_id": "01jx...",
  "from": "sender@example.com",
  "to": ["agent@smtp.ataca.io"],
  "subject": "Re: Hello",
  "raw_message": "<base64-encoded RFC 5322>",
  "received_at": "2025-01-15T10:30:00Z"
}
```

Reply tracking: omit reply_to and rail injects a VERP address. Replies
arrive as type "reply" with in_reply_to set to the original message ID.

Hard bounces of messages you sent arrive as type "bounce" (no raw_message;
message_id is a unique bounce-event id, original_message_id correlates), with bounced_recipient, bounce_status
(e.g. "5.1.1"), bounce_diagnostic, and bounce_type "hard". The bounced
recipient is also auto-suppressed. Soft bounces do not fire a webhook.

## Check delivery status

GET /api/v1/messages/{id}/deliveries (mTLS required)

Returns per-recipient outcomes: delivered, bounced, or deferred.

## Endpoints

- POST /api/v1/send — send email (mTLS)
- GET /api/who — inspect your client cert (mTLS)
- GET /api/v1/messages/{id}/deliveries — delivery status (mTLS)
- GET /healthz — liveness
- GET /readyz — readiness
- GET /stats — relay statistics (JSON)
- GET /openapi.yaml — OpenAPI 3.1 spec
- GET /agents — human-readable agent integration guide
- GET /.well-known/ai-plugin.json — AI plugin manifest

## Links

- Agent guide: https://smtp.ataca.io/agents
- API docs: https://smtp.ataca.io/docs
- OpenAPI spec: https://smtp.ataca.io/openapi.yaml