# Hep.gg Email API

Send transactional email with low latency. Authentication is a per-key
bearer token; create as many keys as you like at /dashboard/email/api-keys.

Base URL: https://hep.gg
Auth: Authorization: Bearer <email-key>

## Endpoints

### POST /api/v1/email/send
Send one or more emails. Auth: bearer token in Authorization header.

Request body (JSON):
  to         string | string[]   required. 1-N recipients.
  cc         string | string[]   optional.
  bcc        string | string[]   optional.
  subject    string              optional. Truncated to 988 chars.
  html       string              one of html/text required. <= 500KB combined.
  text       string              one of html/text required.
  from       string              optional. Must be an address you can send from.
                                 Defaults to your default sender.
  fromName   string              optional. Display name override.
  replyTo    string              optional.

Limits:
  - 100 recipients max per call (to + cc + bcc).
  - 500KB max body (html + text combined).
  - 120 calls/min/key (HTTP 429 with Retry-After when exceeded).
  - Duplicate recipients are de-duped before billing.

Billing:
  - 1 credit per distinct recipient (to + cc + bcc).
  - 30-day unlimited tier active: zero credits charged.
  - Terminal SMTP failures (e.g. invalid syntax that passed validation)
    auto-refund the request.

Responses:
  200 OK (sent immediately):
    {
      "ok": true,
      "data": {
        "messageId": "abc123...",
        "smtpMessageId": "<rfc5322-id>",
        "status": "sent",
        "from": "noreply@hep.gg",
        "recipients": 1,
        "creditsCharged": 1
      }
    }

  202 Accepted (queued; provider daily cap reached):
    {
      "ok": true,
      "data": {
        "messageId": "abc...",
        "status": "queued",
        "recipients": 1,
        "creditsCharged": 1,
        "retryHint": "Daily provider cap reached; will retry within 24h."
      }
    }

  400 Bad Request: validation failures (bad address, missing body, too many recipients).
  401 Unauthorized: missing / invalid bearer.
  402 Payment Required: insufficient credits.
    { "ok": false, "error": "...", "code": "INSUFFICIENT_CREDITS" }
  403 Forbidden: key disabled, or 'from' is not in your assigned senders.
  413 Payload Too Large: body over 500KB.
  429 Too Many Requests: rate limited. Honor Retry-After (seconds).
  502 Bad Gateway: terminal SMTP failure. Credits refunded.

The messageId returned is the same id you'll see on the dashboard logs.

### Example
curl -X POST https://hep.gg/api/v1/email/send \
  -H "Authorization: Bearer hyd-mail-..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Welcome",
    "html": "<h1>Hello</h1>"
  }'

## Dashboard endpoints (cookie auth - not for programmatic use)
These exist for the web UI only and require an active Hep.gg session. List
included for completeness:
  GET    /api/v1/email/account
  GET    /api/v1/email/addresses
  GET    /api/v1/email/cap-status
  GET    /api/v1/email/keys
  POST   /api/v1/email/keys
  PATCH  /api/v1/email/keys/:id
  POST   /api/v1/email/keys/:id/rotate
  DELETE /api/v1/email/keys/:id
  GET    /api/v1/email/logs?limit=&offset=&keyId=
  GET    /api/v1/email/credits
  GET    /api/v1/email/credits/bundles
  GET    /api/v1/email/credits/history
  POST   /api/v1/email/credits/checkout
  POST   /api/v1/email/credits/checkout/unlimited