RelyKit API

Validates and queues one message. The response is the stored message with status `queued`; poll `GET /emails/{id}` or take webhooks for the outcome. The host in `from` must be a verified domain on this account, or a subdomain of one, otherwise the request is refused with `domain_not_verified`. Recipients on the account's suppression list are dropped before the message is stored and listed in `suppressed`; if every recipient is dropped, the message is stored with status `cancelled` and nothing is sent. Send `scheduled_at` to hold the message until then, and `unsubscribe: true` to add the `List-Unsubscribe` headers that Gmail and Yahoo require of bulk senders — that one needs exactly one recipient, because the link is signed for a single address. In place of `subject`, `html` and `text`, a message may name a `template` and pass `variables`; the template provides all three, and setting both is a 422. The stored message records which template and which version rendered it. A `template` that matches no template on this account is a 404, as is a `template_version` that does not exist.

Responses: 200, 201, 400, 401, 403, 404, 413, 422, 429, 503

The stored message, including its current status, the recipients that were dropped as suppressed, the number of send attempts, and `last_error` if a send failed.

Responses: 200, 401, 403, 404, 429

Every event recorded for this message, oldest first. There is one row per recipient per SES event, so a message to three addresses that all bounce has three `email.bounced` events.

{
  "data": [
    {
      "id": "6c1e0f2a-3b44-4d10-9f21-6b2c8a0d5e77",
      "type": "email.sent",
      "email_id": "3f8a1c2e-9f6d-4c71-8c3a-6a5f2b1d0e44",
      "recipient": "you@example.com",
      "data": {},
      "occurred_at": "2026-04-01T09:00:01.120Z"
    },
    {
      "id": "8a2d5b31-7c09-4e88-b0f2-1d4e6a7c9b30",
      "type": "email.delivered",
      "email_id": "3f8a1c2e-9f6d-4c71-8c3a-6a5f2b1d0e44",
      "recipient": "you@example.com",
      "data": {
        "smtp_response": "250 2.0.0 OK 1743498002 x12si"
      },
      "occurred_at": "2026-04-01T09:00:02.480Z"
    }
  ]
}

Responses: 200, 401, 403, 404, 429

Validates every entry before writing anything, and writes the whole batch in a single transaction. One invalid entry fails the call, naming its position, so a caller never has to reconcile a partly sent batch. Suppressed recipients do not fail the batch: as on the single send, a message whose every recipient is suppressed is stored with status cancelled. A batch larger than the account has allowance left for is refused whole, and the error says how much room remains. In place of `subject`, `html` and `text`, a message may name a `template` and pass `variables`; the template provides all three, and setting both is a 422. The stored message records which template and which version rendered it. A template failure in a batch is always reported as a 422 naming the entry, even where the same failure on a single send would be a 404.

{
  "emails": [
    {
      "from": "Acme <receipts@acme.com>",
      "to": "kai@example.com",
      "subject": "Your receipt",
      "html": "<p>Thanks for your order.</p>",
      "idempotency_key": "order-6be1f2-receipt"
    },
    {
      "from": "Acme <receipts@acme.com>",
      "to": "noor@example.com",
      "subject": "Your receipt",
      "html": "<p>Thanks for your order.</p>",
      "idempotency_key": "order-7cd2a9-receipt"
    }
  ]
}

Responses: 200, 201, 401, 403, 409, 422, 429, 503

Stops a message that has not been handed to Amazon SES yet, which in practice means one that was scheduled for later. Cancelling an already cancelled message succeeds and changes nothing. Anything sent, delivered, bounced or failed cannot be taken back and answers 409.

Responses: 200, 401, 404, 409

Every template on the account, live ones first and then by when they were last touched. Each carries `version_count` and `message_count`; the versions themselves are on `GET /templates/{ref}`.

{
  "data": [
    {
      "id": "0b6f1d3c-2c47-4a56-9b1e-8c2f7a0d4e11",
      "slug": "welcome",
      "name": "Welcome",
      "description": "Sent when someone finishes signing up.",
      "current_version": 2,
      "archived": false,
      "version_count": 2,
      "message_count": 1840,
      "created_at": "2026-03-20T10:00:00.000Z",
      "updated_at": "2026-04-01T08:30:00.000Z"
    },
    {
      "id": "2d7e4a90-6b31-4c02-8f77-3a1b5c9d0e22",
      "slug": "order-receipt",
      "name": "Order receipt",
      "description": "",
      "current_version": null,
      "archived": false,
      "version_count": 1,
      "message_count": 0,
      "created_at": "2026-03-28T14:05:00.000Z",
      "updated_at": "2026-03-28T14:05:00.000Z"
    }
  ]
}

Responses: 200, 401, 403, 429

Creates the template and its version 1 in one call, published and immediately sendable unless you pass `publish: false`. The source is compiled before anything is stored: every variable it references must be declared in `variables`, and a name it loops over with `{{#each}}` must be declared as an array. Both are refused here rather than at send time. The template language is `{{ name }}`, `{{#if}}`, `{{#unless}}` and `{{#each}}` with `{{ this.field }}` for the current item; values substituted into `html` are HTML-escaped, and there is no unescaped-output syntax. `slug` is derived from `name` when you leave it out. It is how a send names the template, and renaming the template never changes it.

{
  "id": "0b6f1d3c-2c47-4a56-9b1e-8c2f7a0d4e11",
  "slug": "welcome",
  "name": "Welcome",
  "description": "Sent when someone finishes signing up.",
  "current_version": 1,
  "archived": false,
  "created_at": "2026-03-20T10:00:00.000Z",
  "updated_at": "2026-04-01T08:30:00.000Z",
  "version": {
    "version": 1,
    "subject": "Welcome to Acme, {{first_name}}",
    "html": "<p>Hi {{first_name}}, thanks for joining.</p>{{#if items}}<ul>{{#each items}}<li>{{this.name}}</li>{{/each}}</ul>{{/if}}",
    "text": "Hi {{first_name}}, thanks for joining.",
    "variables": [
      {
        "name": "first_name",
        "type": "string",
        "required": true,
        "description": "Used in the greeting"
      },
      {
        "name": "items",
        "type": "array",
        "required": false,
        "description": "What they ordered",
        "default": []
      }
    ],
    "notes": "",
    "created_at": "2026-04-01T08:30:00.000Z"
  }
}

Responses: 201, 400, 401, 403, 409, 422, 429

The template with every one of its versions under `versions`, newest first, so a rollback target can be read off the same response. `current_version` says which one is live.

{
  "id": "0b6f1d3c-2c47-4a56-9b1e-8c2f7a0d4e11",
  "slug": "welcome",
  "name": "Welcome",
  "description": "Sent when someone finishes signing up.",
  "current_version": 2,
  "archived": false,
  "created_at": "2026-03-20T10:00:00.000Z",
  "updated_at": "2026-04-01T08:30:00.000Z",
  "versions": [
    {
      "version": 2,
      "subject": "Welcome to Acme, {{first_name}}",
      "html": "<p>Hi {{first_name}}, thanks for joining.</p>{{#if items}}<ul>{{#each items}}<li>{{this.name}}</li>{{/each}}</ul>{{/if}}",
      "text": "Hi {{first_name}}, thanks for joining.",
      "variables": [
        {
          "name": "first_name",
          "type": "string",
          "required": true,
          "description": "Used in the greeting"
        },
        {
          "name": "items",
          "type": "array",
          "required": false,
          "description": "What they ordered",
          "default": []
        }
      ],
      "notes": "Shorter subject line",
      "created_at": "2026-04-01T08:30:00.000Z"
    },
    {
      "version": 1,
      "subject": "Welcome to Acme, {{first_name}}",
      "html": "<p>Hi {{first_name}}, thanks for joining.</p>{{#if items}}<ul>{{#each items}}<li>{{this.name}}</li>{{/each}}</ul>{{/if}}",
      "text": "Hi {{first_name}}, thanks for joining.",
      "variables": [
        {
          "name": "first_name",
          "type": "string",
          "required": true,
          "description": "Used in the greeting"
        },
        {
          "name": "items",
          "type": "array",
          "required": false,
          "description": "What they ordered",
          "default": []
        }
      ],
      "notes": "first cut",
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ]
}

Responses: 200, 401, 403, 404, 429

Appends the next version. Nothing existing changes: versions are immutable, and whatever is live stays live until something publishes this one — either `publish: true` here, or `POST /templates/{ref}/publish` later. The source is compiled exactly as on create, so an undeclared variable is refused now rather than at send time. Variables are declared per version, so a new version may declare a different set from the live one.

{
  "subject": "Welcome to Acme, {{first_name}}",
  "html": "<p>Hi {{first_name}}, thanks for joining.</p>",
  "text": "Hi {{first_name}}, thanks for joining.",
  "variables": [
    {
      "name": "first_name",
      "description": "Used in the greeting"
    }
  ],
  "notes": "Shorter subject line",
  "publish": true
}

Responses: 201, 400, 401, 403, 404, 422, 429

One version, exactly as it was saved. Since versions never change, this is what a message sent against that version was rendered from.

Responses: 200, 401, 403, 404, 429

Points the template at a version that already exists, which makes releasing and rolling back the same operation: publishing version 1 again after version 2 went wrong is instant, and the message history still records which version sent what.

{
  "id": "0b6f1d3c-2c47-4a56-9b1e-8c2f7a0d4e11",
  "slug": "welcome",
  "name": "Welcome",
  "description": "Sent when someone finishes signing up.",
  "current_version": 2,
  "archived": false,
  "created_at": "2026-03-20T10:00:00.000Z",
  "updated_at": "2026-04-01T08:30:00.000Z"
}

Responses: 200, 400, 401, 403, 404, 422, 429

Archiving rather than deleting: messages reference the template, and the history of what was sent should not disappear because someone tidied up. An archived template is still readable and still listed with `?archived=true`, but sending with it is refused until it is restored. Send `{ "archived": false }` to restore. An absent or unreadable body archives, so a bare POST is the same as asking to archive.

{
  "id": "0b6f1d3c-2c47-4a56-9b1e-8c2f7a0d4e11",
  "slug": "welcome",
  "name": "Welcome",
  "description": "Sent when someone finishes signing up.",
  "current_version": 2,
  "archived": true,
  "created_at": "2026-03-20T10:00:00.000Z",
  "updated_at": "2026-04-01T08:30:00.000Z"
}

Responses: 200, 401, 403, 404, 429

Renders the published version — or the one named in `version` — against the variables given, and returns the subject and bodies a send would produce. Nothing is stored and no message is created. The variables are checked exactly as at send time, so this is also how you prove a draft before publishing it. The request body is required: send `{}` for a template that declares nothing.

Responses: 200, 400, 401, 403, 404, 422, 429

The built-in library: complete, tested transactional emails you can copy into your account and edit. They are the same for every account and nothing here is yours yet — adopting one is what makes a copy you own. The response also carries `categories`, the set of categories present, so a picker can be built without hard-coding them.

Responses: 200

Copies the starter in as a normal template of your own, published at version 1 and immediately sendable. From then on it is yours: editing it creates new versions and nothing about it tracks the library. The slug is taken from the starter. If you already have a template with that slug, the copy gets a numbered one rather than overwriting what is there.

Responses: 201, 404

Every domain on the account, oldest first.

Responses: 200, 401, 403, 429

Creates the domain as an SES identity with Easy DKIM and a custom MAIL FROM subdomain, and returns the DNS records to publish. The domain stays `pending` until every required record resolves and SES reports DKIM and MAIL FROM as SUCCESS; the worker re-checks pending domains every few minutes, and `POST /domains/{id}/verify` checks immediately. A domain name exists once across the whole service, because it is one SES identity.

{
  "name": "acme.com"
}

Responses: 201, 400, 401, 403, 409, 422, 429

The domain as of the last check. Each entry in `records` carries the result of that check and the values DNS actually returned, so you can show which record is wrong.

Responses: 200, 401, 403, 404, 429

Deletes the domain and its SES identity. Messages already sent from it keep their history; new sends from that host are refused with `domain_not_verified`.

Responses: 204, 401, 403, 404, 429

Resolves every expected record against the public resolvers, asks SES for its own view, stores the outcome, and returns the updated domain. Use it after publishing the records rather than waiting for the poller. A domain that has gone `failed` is only re-checked this way.

Responses: 200, 401, 403, 404, 429

Every endpoint on the account, oldest first. Secrets are not included.

Responses: 200, 401, 403, 429

Creates an endpoint and returns its signing `secret`. **The secret is returned only by this call** and never again, so store it now. An empty or omitted `event_types` means every event type.

Responses: 201, 400, 401, 403, 422, 429

Responses: 200, 401, 403, 404, 429

Only the fields you send are changed. Setting `enabled` to `true` on an endpoint that was disabled by repeated failures also clears its failure count, so it starts fresh. The signing secret cannot be changed or read here.

Responses: 200, 400, 401, 403, 404, 422, 429

Removes the endpoint and its pending deliveries.

Responses: 204, 401, 403, 404, 429

Posts a synthetic `webhook.test` event to the endpoint right now, signed exactly like a real one, and returns the attempt. The call waits for the delivery, so a slow endpoint makes it slow; the request has no body. A `200` here does not mean the endpoint accepted it — read `status` and `status_code` on the returned delivery.

{
  "id": "b71c4d90-2f8e-4a63-9c15-7e0a3d6b8f21",
  "webhook_id": "9d2f4a11-5c8b-4e37-b6a0-2f1e9c4d7a55",
  "event_id": null,
  "status": "delivered",
  "attempts": 1,
  "status_code": 204,
  "response_excerpt": "",
  "last_error": null,
  "next_attempt_at": "2026-04-01T09:00:00.000Z",
  "delivered_at": "2026-04-01T09:00:00.412Z",
  "created_at": "2026-04-01T09:00:00.000Z"
}

Responses: 200, 401, 403, 404, 429

The 50 most recent delivery attempts for this endpoint, newest first, with the status code and the first 500 characters of the response body.

Responses: 200, 401, 403, 404, 429

The account's suppression list, newest first. Pass `email` to look one address up exactly, which returns zero or one entry and ignores `limit`.

{
  "data": [
    {
      "email": "bounced@example.com",
      "reason": "hard_bounce",
      "source_email_id": "3f8a1c2e-9f6d-4c71-8c3a-6a5f2b1d0e44",
      "created_at": "2026-04-01T09:00:03.900Z"
    }
  ]
}

Responses: 200, 401, 403, 422, 429

Adds an address by hand, or changes the reason on one that is already listed. Only `manual` and `unsubscribe` may be written here; `hard_bounce`, `soft_bounces` and `complaint` are written by the service from delivery events.

{
  "email": "angry@example.com",
  "reason": "manual"
}

Responses: 201, 400, 401, 403, 422, 429

Removes the address, so it can be sent to again. Do this only when you know why it was listed: re-sending to a hard bounce or a complainer is what costs a sender its reputation.

Responses: 204, 401, 403, 404, 422, 429

The account this API key belongs to, including the daily limit actually enforced and, if sending is paused, why.

Responses: 200, 401, 403, 429

Turns open and click tracking on or off. Tracked accounts send through a second SES configuration set with a custom redirect domain, so untracked mail carries no pixel and no rewritten links. `tracking` is the only field that may be changed, and it is required.

{
  "tracking": true
}

Responses: 200, 400, 401, 403, 422, 429

How many messages were handed to SES over the last `window_hours`, and what share of them hard bounced or drew a complaint. `sent` counts messages that reached SES, and `bounced` and `complained` count messages with at least one such recipient, so the rates are per message rather than per recipient. The service pauses an account above 5% bounces or 0.25% complaints, once it has sent enough messages in the window for a ratio to mean anything. A paused account's keys fail with 403 until an administrator resumes it.

Responses: 200, 401, 403, 429

Returns 200 as long as the HTTP server is up. It does not check the database, and it needs no API key.

{
  "ok": true
}

Responses: 200

Posts an event from your application. It may start a flow, wake a flow that was waiting for it, or neither, and is recorded either way so a trigger that did nothing can still be looked at. The id is yours, and posting the same one twice runs the flow once. Derive it from whatever happened rather than generating a fresh one per attempt.

Responses: 200, 202, 422