---
title: Hep.gg Email API (LLM)
description: Send transactional email over an HTTPS API with a per-key bearer token, billed per recipient.
---

# 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. The same
key also works as the password for the SMTP relay (smtp.hep.gg:587, STARTTLS).

Base URL: https://hep.gg
Auth: Authorization: Bearer <email-key>   (keys look like hyd-mail-...)

## 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.
  text       string              one of html/text required.
  from       string              optional. Must be an address you can send from.
                                 Defaults to your default sender (noreply@hep.gg
                                 is available to every account).
  fromName   string              optional. Display name override.
  replyTo    string              optional.
  attachments object[]           optional. File attachments; see Attachments below.

Limits:
  - 100 recipients max per call (to + cc + bcc).
  - 10 MB max decoded body (html + text combined). The HTTPS JSON parser accepts
    up to 15 MB of request payload, but the 10 MB decoded-body cap is binding;
    over it returns 413.
  - 120 calls/min/key (HTTP 429 with Retry-After when exceeded).
  - Duplicate recipients are de-duped before billing.

Attachments:
  Optional `attachments` array. Each item is one of:
    - { "uploadId": "<id>", "filename"?: "<override>" }  a file already uploaded
      to hep.gg on your own account (read server-side, keeps the request small).
    - { "filename": "f.pdf", "content": "<base64>", "contentType"?: "..." }  inline.
  Limits: up to 10 attachments, 15 MB each, and body + attachments combined under
  18 MB before encoding. Inline base64 also counts against the 15 MB request
  payload. Attachments add no credit cost (billing stays per recipient).

Billing:
  - 1 credit per distinct recipient (to + cc + bcc). No unlimited tier.
  - 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: decoded body over 10 MB, or attachments over their size limits.
  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/history