API reference

GET /api/v1/contacts

List contacts. Returns the workspace's contacts, newest first by default, with pagination. Optionally search by email or name; filter by status, tag, list membership, source and the date added — the same filters the contacts page, the CSV export and the bulk endpoint's `filter` take, combinable; and sort. Archived contacts are left out unless `status=archived` asks for them. Requires `contacts:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/contacts?page=1&limit=50" \
  -H "x-api-key: sb_live_…"

Responses

{
  "contacts": [
    {
      "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "subscribed",
      "custom_fields": {
        "plan": "pro"
      },
      "source": "api",
      "language": "en",
      "subscribed_at": "2026-09-01T10:00:00.000Z",
      "unsubscribed_at": null,
      "created_at": "2026-09-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "total_pages": 25
  }
}

POST /api/v1/contacts

Create a contact. Creates a subscribed contact. The email is trimmed, lowercased, validated (at most 254 characters) and must be unique in the workspace; names are at most 100 characters and `custom_fields` must satisfy the CustomFields limits, otherwise `400`. An address on the workspace's suppression list is refused with `409`: one that **unsubscribed** can be re-added by sending `resubscribe: true` (you are asserting the person gave you new consent; the suppression entry is removed once the contact is created), one that **bounced** or **complained** never can, and one that was **deleted** only returns when the person signs up again through a form. Counts against the plan's contact cap. Enrols the contact in every active `contact_created` automation. Requires `contacts:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/contacts" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "source": "website",
  "language": "fr",
  "custom_fields": {
    "plan": "pro",
    "region": "London",
    "seats": 3,
    "trial": false
  },
  "resubscribe": false
}'

Responses

{
  "contact": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "subscribed",
    "custom_fields": {
      "plan": "pro"
    },
    "source": "api",
    "language": "en",
    "subscribed_at": "2026-09-01T10:00:00.000Z",
    "unsubscribed_at": null,
    "created_at": "2026-09-01T10:00:00.000Z"
  }
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

GET /api/v1/contacts/{id}

Get a contact. Returns one contact including its tags. Requires `contacts:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/contacts/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "contact": null
}

PATCH /api/v1/contacts/{id}

Update a contact. Partially updates a contact. Only `email`, `first_name`, `last_name`, `status`, `source` and `custom_fields` may be sent, plus the flags `resubscribe`, `suppress` and `replace_custom_fields`; any other key is rejected with `400`. An updated email is lowercased and validated. **Custom fields merge.** `custom_fields` sets the keys you send and keeps every other key the contact already has; a key sent as `null` is removed. Send `replace_custom_fields: true` to replace the whole object instead (the behaviour before 2026-09-14). `{}` without the flag changes nothing. **Unsubscribing.** Setting `status` to `unsubscribed` records `unsubscribed_at` — and only that: the address stays off campaigns but is not blocked, so a later import or signup form can bring it back as a subscriber. Add `suppress: true` to also put the address on the workspace's suppression list as `unsubscribed`, which no import, API call or form can undo until the person opts in again. The list is written after the update succeeds; a bounce or complaint already on file is never downgraded. **Re-subscribing.** The suppression list is checked whenever the update would make a suppressed address a subscriber — renaming the contact to it, or setting `status` back to `subscribed` — and refuses with `409`. An `unsubscribed` entry can be lifted by sending `resubscribe: true` (you are asserting the person gave you new consent): the contact becomes `subscribed` with `subscribed_at` set to now, `unsubscribed_at` cleared and `source` unchanged, and the suppression entry is removed once the update succeeds. Bounced, complained and deleted addresses cannot be re-subscribed this way. Requires `contacts:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/contacts/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Janet",
  "custom_fields": {
    "plan": "business",
    "trial_ends": null
  }
}'

Responses

{
  "contact": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "subscribed",
    "custom_fields": {
      "plan": "pro"
    },
    "source": "api",
    "language": "en",
    "subscribed_at": "2026-09-01T10:00:00.000Z",
    "unsubscribed_at": null,
    "created_at": "2026-09-01T10:00:00.000Z"
  },
  "suppressed": true
}

{
  "error": "Unknown field(s): tenant_id. Updatable fields: email, first_name, last_name, status, source, custom_fields"
}

{
  "error": "Contact not found"
}

DELETE /api/v1/contacts/{id}

Delete a contact. Permanently deletes a contact and its tag and list memberships. The address is added to the workspace's suppression list as `deleted` (so it cannot be re-created through the API or re-imported as subscribed) and replaced in the send log by an anonymous placeholder. A plain delete keeps a masked form of the address on that row and a workspace admin can lift the block later; `?mode=erase` is the request to be forgotten — the suppression row keeps the hash alone and is never lifted from the app. To remove a contact from the working list WITHOUT blocking the address, set `status: "archived"` with PATCH instead. Requires `contacts:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/contacts/id?mode=delete" \
  -H "x-api-key: sb_live_…"

Responses

GET /api/v1/contacts/{id}/tags

List a contact's tags. Returns the tags attached to a contact with the time each was assigned. Requires `tags:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/contacts/id/tags" \
  -H "x-api-key: sb_live_…"

Responses

{
  "tags": [
    {
      "id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
      "name": "Customer",
      "color": "#2563EB",
      "assigned_at": "2026-09-01T10:05:00.000Z"
    }
  ]
}

POST /api/v1/contacts/{id}/tags

Add a tag to a contact. Attaches an existing tag to the contact and enrols the contact in active `tag_added` automations whose `trigger_config.tag_id` matches. Requires `tags:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/contacts/id/tags" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33"
}'

Responses

{
  "contact_tag": {
    "contact_id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "tag_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
    "created_at": "2026-09-01T10:05:00.000Z"
  }
}

{
  "error": "tag_id is required"
}

{
  "error": "Tag not found"
}

{
  "error": "Contact already has this tag"
}

DELETE /api/v1/contacts/{id}/tags/{tagId}

Remove a tag from a contact. Detaches the tag from the contact. Requires `tags:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/contacts/id/tags/tagId" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "This tag is not associated with the contact"
}

POST /api/v1/contacts/bulk

Bulk action on contacts. Runs one action over a set of contact IDs: `unsubscribe`, `archive`, `restore`, `delete`, `erase`, `add_tag`, `remove_tag`, `add_to_list`, `remove_from_list` or `export`. `archive` takes contacts out of the working list without touching their addresses (hidden from listings, never mailed, not counted; the status they had is kept for `restore`, which puts it back — a formerly subscribed contact whose address was blocked meanwhile comes back `unsubscribed`); it answers `503` until the workspace's database has the archive columns. `erase` is the data-subject request: like `delete`, but the suppression row keeps the hash alone and can never be lifted. Non-string IDs are dropped; IDs from other workspaces are ignored; `tag_id` / `list_id` must belong to this workspace. `export` responds with a CSV file instead of JSON. `unsubscribe` sets every selected `subscribed` contact to `unsubscribed` (`unsubscribed_at` now, one `contact.unsubscribed` event each) and leaves contacts already opted out alone; with `suppress: true` every selected address is also put on the suppression list as `unsubscribed` — blocked, not just marked — so no import, API call or signup form can re-add it until the person opts in again (a bounce or complaint already on file is never downgraded). Its response carries `unsubscribed`, `already_unsubscribed`, `suppressed` and `blocked`. `delete` also puts each address on the suppression list (reason `deleted`, source `delete`, masked form kept — a workspace admin can lift it) and pseudonymises it in the send log, exactly like deleting one contact. `add_to_list` adds only subscribed contacts, confirmed on a single opt-in list (they enrol in `list_joined` automations and fire `contact.list_joined`) or unconfirmed on a double opt-in list and on every Free-plan list — a bulk add never sends confirmation email; its response says how many were `added`, were `already_member`, or were `skipped_not_subscribed`. `remove_from_list` fires `contact.list_left` for each membership removed. Tag counts (`tagged`, `untagged`, `deleted`) are the number of IDs submitted; list counts are the number actually affected. Requires `contacts:write`; `export` additionally requires `contacts:export`, the same grant as `GET /api/v1/contacts/export`, and is refused before any contact is read without it.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/contacts/bulk" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "add_tag",
  "contact_ids": [
    "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  ],
  "tag_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33"
}'

Responses

{
  "success": true,
  "deleted": 1,
  "erased": true,
  "archived": 1,
  "already_archived": 1,
  "restored": 1,
  "not_archived": 1,
  "tagged": 1,
  "untagged": 1,
  "added": 1,
  "already_member": 1,
  "skipped_not_subscribed": 1,
  "membership": "confirmed",
  "removed": 1,
  "unsubscribed": 1,
  "already_unsubscribed": 1,
  "suppressed": 1,
  "blocked": true
}

{
  "error": "contact_ids array or filter is required"
}

{
  "error": "Tag not found"
}

{
  "error": "Bulk action failed"
}

{
  "error": "Archiving is not available on this workspace yet: a database update is still to be applied. Nothing was changed."
}

GET /api/v1/contacts/export

Export contacts as CSV. Every contact in the workspace (or those matching the same `q` / `status` / `tag` / `list` / `source` / `from` / `to` filters as `GET /api/v1/contacts`) as a CSV download with tags, lists and custom fields. Large audiences are exported in full; there is no page limit. Every cell is quoted, and a cell beginning with `=`, `+`, `-` or `@` is prefixed with a single quote so spreadsheets show it as text rather than evaluating it as a formula (the bulk `export` action does the same). Requires `contacts:export` — not `contacts:read`, which reads contacts a page at a time and cannot download the list.

Example request

curl -X GET "https://sendbeam.io/api/v1/contacts/export?q=string&status=subscribed" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Forbidden: contacts:export permission required"
}

POST /api/v1/contacts/import

Import contacts from CSV. Uploads a CSV (multipart field `file`, at most 5 MB — roughly 50,000 rows) and creates contacts from it. Headers are case-insensitive with spaces and punctuation folded to underscores. Recognised columns: `email` (required), `first_name`, `last_name`, `status` (`subscribed`, `unsubscribed`, `bounced`, `complained`, `pending`; aliases `active`→subscribed, `cleaned`→bounced, `cancelled`/`canceled`→unsubscribed, `junk`/`spam`→complained, `unconfirmed`→pending; blank → `default_status`), `tags` (`;` or `|` separated, up to 20 per row, names up to 60 characters), `subscribed_at` (aliases `opted_in_at`, `signup_at`, `optin_time`, `created_at`; ISO 8601, `YYYY-MM-DD HH:MM:SS`, `YYYY-MM-DD` or `DD/MM/YYYY`; unparseable → now, future → now), `unsubscribed_at` (aliases `opted_out_at`, `unsub_time`), `source` (per row, up to 40 characters, overrides the request field), and the consent columns `consent_ip`, `consent_at` (aliases `confirm_time`, `opt_in_confirmed_at`) and `consent_source`, stored under `custom_fields` as `consent_ip`, `consent_confirmed_at` (normalised ISO 8601) and `consent_source`. Every other column becomes a custom field keyed by its snake_cased header (values up to 200 characters; keys that fail validation or exceed the 50-key limit are listed in `dropped_columns`; empty cells store nothing). Rows with `pending` status are never imported (`skipped_unconfirmed`). `unsubscribed`, `bounced` and `complained` rows are created with that status, `unsubscribed_at` set from the file or now, and recorded on the workspace suppression list (`suppressed`); they do not count towards the plan's contact cap — only rows that will be `subscribed` do, and the file is read only up to that allowance (plus one), so a `403` means the subscribed rows exceed the slots left. Addresses already on the suppression list are imported as `unsubscribed` whatever the file says. Repeated addresses within the file are merged (strongest status wins; tags and fields union). Existing contacts: with `skip_duplicates=true` (default) their names and status are left alone but the file's tags are attached, its custom fields merged in (file values win for the keys it carries), and a `subscribed` contact is escalated to the file's `unsubscribed`/`bounced`/`complained` status (never the reverse) — these are counted in `updated`; `skip_duplicates=false` also refreshes their names and source. Tags are matched case-insensitively against existing names and created when missing (at most 200 distinct names per import). `list_id` adds every subscribed contact in the file to that list: confirmed on a single opt-in list (`list_added`), unconfirmed on a double opt-in list or in a Free-plan workspace (`list_pending_confirmation`) — the importer never sends confirmation emails. **No automation runs for an imported contact unless `run_automations=true`**: an import brings people in, which is not the same decision as greeting them, and a list moved from another provider is full of people who were welcomed long ago. With it, newly created subscribed contacts enter active `contact_created` automations and contacts confirmed onto a list enter its `list_joined` automations; `automations_enrolled` reports how many enrolments that produced. Rows whose email is missing, malformed or over 254 characters, whose name is over 100 characters, or whose status is unrecognised are counted as `invalid`. Requires `contacts:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/contacts/import" \
  -H "x-api-key: sb_live_…"

Responses

{
  "imported": 118,
  "updated": 6,
  "skipped": 6,
  "skipped_duplicates": 6,
  "suppressed": 23,
  "skipped_unconfirmed": 4,
  "invalid": 2,
  "skipped_undeliverable": 4,
  "undeliverable_domains": [
    {
      "domain": "gmial.com",
      "rows": 2
    },
    {
      "domain": "example.com",
      "rows": 1,
      "reason": "example domain — reserved for documentation, never a real mailbox"
    },
    {
      "domain": "oldcompany.co.uk",
      "rows": 1
    }
  ],
  "skipped_placeholder": 1,
  "placeholder_addresses": [
    {
      "email": "test@example.com",
      "reason": "example domain — reserved for documentation, never a real mailbox"
    }
  ],
  "tags_created": 2,
  "tags_attached": 140,
  "custom_field_keys": [
    "company",
    "consent_ip",
    "consent_confirmed_at",
    "consent_source"
  ],
  "dropped_columns": [
    "Notes (long)"
  ],
  "list_added": 0,
  "list_pending_confirmation": 95,
  "truncated": false
}

{
  "error": "A file field named \"file\" is required"
}

{
  "error": "Contact not found"
}

{
  "error": "List not found"
}

{
  "error": "The file is too large. Uploads are limited to 5 MB — split the CSV and import it in parts."
}

{
  "error": "No valid contacts found. The CSV must have an \"email\" column header and at least one data row.",
  "invalid": 3,
  "skipped_unconfirmed": 0
}

{
  "error": "Failed to import contacts",
  "details": "duplicate key value violates unique constraint"
}

GET /api/v1/custom-fields

List custom fields. Every custom field declared in the workspace, in display order, with how many contacts carry each key (`uses`, null when usage counts are unavailable). Also lists `unregistered` keys — keys contacts carry that no field names yet (register them with `POST /custom-fields/scan`) — and `unaddressable` keys, which contain characters a merge tag cannot use and are never registered. Requires `contacts:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/custom-fields" \
  -H "x-api-key: sb_live_…"

Responses

{
  "fields": [
    {
      "id": "5e2b8c1a-4d3f-4a6b-9c8d-1e2f3a4b5c6d",
      "key": "plan",
      "label": "Plan",
      "type": "dropdown",
      "options": [
        "free",
        "pro",
        "business"
      ],
      "position": 0,
      "uses": 1180,
      "created_at": "2026-09-14T09:00:00.000Z",
      "updated_at": "2026-09-14T09:00:00.000Z"
    },
    {
      "id": "6f3c9d2b-5e4a-4b7c-8d9e-2f3a4b5c6d7e",
      "key": "renewal_date",
      "label": "Renewal date",
      "type": "date",
      "options": [],
      "position": 1,
      "uses": 312,
      "created_at": "2026-09-14T09:00:00.000Z",
      "updated_at": "2026-09-14T09:00:00.000Z"
    }
  ],
  "unregistered": [
    {
      "key": "legacy_score",
      "uses": 4
    }
  ],
  "unaddressable": [],
  "usage_available": true
}

{
  "error": "Contact not found"
}

POST /api/v1/custom-fields

Create a custom field. Declares a field. `key` is 1–64 characters of letters, digits and underscores, unique in the workspace and **cannot be changed afterwards** (change the `label`, or delete the field and add another). `type` defaults to `text`; a `dropdown` needs at least one option. A key contacts already carry may be declared — if the chosen type does not fit some stored values the request is refused with `409` and the count (`violations`), until `confirm_violations: true` is sent; stored values are never rewritten. At most 100 fields per workspace. Requires `contacts:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/custom-fields" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "string",
  "label": "string",
  "type": "text",
  "options": [
    "string"
  ],
  "confirm_violations": false
}'

Responses

{
  "field": {
    "id": "5e2b8c1a-4d3f-4a6b-9c8d-1e2f3a4b5c6d",
    "key": "plan",
    "label": "Plan",
    "type": "dropdown",
    "options": [
      "free",
      "pro",
      "business"
    ],
    "position": 0,
    "created_at": "2026-09-14T09:00:00.000Z",
    "updated_at": "2026-09-14T09:00:00.000Z"
  }
}

{
  "error": "Contact not found"
}

{
  "error": "3 contacts hold a value for \"renewal_date\" that is not a valid date (for example \"soon\"). Those values are kept exactly as they are and will be flagged on each contact until someone corrects them. Send confirm_violations: true to change the type anyway.",
  "violations": {
    "count": 3,
    "examples": [
      "soon"
    ],
    "partial": false
  }
}

{
  "error": "Contact not found"
}

PATCH /api/v1/custom-fields/{key}

Update a custom field. Changes `label`, `type` and/or `options`. The key cannot be changed (`400`). A type or option change that stored values would violate is refused with `409` and the count until `confirm_violations: true` is sent; even then no stored value is altered — each is flagged on its contact until someone corrects it, and `violations` in the `200` body says how many. Requires `contacts:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/custom-fields/key" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string",
  "type": "text",
  "options": [
    "string"
  ],
  "confirm_violations": false
}'

Responses

{
  "field": {
    "id": "5e2b8c1a-4d3f-4a6b-9c8d-1e2f3a4b5c6d",
    "key": "plan",
    "label": "Plan",
    "type": "dropdown",
    "options": [
      "free",
      "pro",
      "business"
    ],
    "position": 0,
    "created_at": "2026-09-14T09:00:00.000Z",
    "updated_at": "2026-09-14T09:00:00.000Z"
  },
  "violations": {
    "count": 1,
    "examples": [
      "string"
    ],
    "partial": true
  }
}

{
  "error": "Contact not found"
}

{
  "error": "string",
  "violations": {
    "count": 1,
    "examples": [
      "string"
    ],
    "partial": true
  }
}

{
  "error": "Contact not found"
}

DELETE /api/v1/custom-fields/{key}

Delete a custom field. Removes the field **and its value from every contact** in the workspace, and takes it off every signup form that collected it. Segment rules, automation rules and `{{custom_fields.<key>}}` merge tags that name it are left as they are and stop matching or resolving (the pre-send check reports them). Cannot be undone. A key that an integration keeps sending is registered again, as Text, the next time it arrives. Requires `contacts:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/custom-fields/key" \
  -H "x-api-key: sb_live_…"

Responses

{
  "ok": true,
  "key": "legacy_score",
  "contacts_cleared": 4,
  "forms_updated": 0
}

{
  "error": "Contact not found"
}

POST /api/v1/custom-fields/scan

Register keys already in use. Scans the workspace's contacts for keys that have no field yet and declares each one. The type is inferred only where every stored value agrees (all booleans → `boolean`, all numbers → `number`, all `YYYY-MM-DD` strings → `date`), otherwise `text`, so a scan never declares a type a stored value violates. Keys with characters a merge tag cannot use are reported in `unaddressable` and left alone. Requires `contacts:write`.

Example request

curl -X POST "https://sendbeam.io/api/v1/custom-fields/scan" \
  -H "x-api-key: sb_live_…"

Responses

{
  "ok": true,
  "added": [
    {
      "id": "7a4d0e3c-6f5b-4c8d-9e0f-3a4b5c6d7e8f",
      "key": "legacy_score",
      "label": "Legacy score",
      "type": "number",
      "options": [],
      "position": 2
    }
  ],
  "unaddressable": [
    "Plan Name"
  ]
}

{
  "error": "Contact not found"
}

GET /api/v1/suppressions

Suppression counts, or check one address. Without parameters: how many addresses are on the workspace's suppression list, split by reason. With `?email=`: whether that one address is suppressed, with its reason and when it was added. Addresses are stored as one-way hashes; the list itself is paged by `GET /api/v1/suppressions/list` and downloaded by `GET /api/v1/suppressions/export`. Requires `contacts:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/suppressions?email=jane%40example.com" \
  -H "x-api-key: sb_live_…"

Responses

{
  "count": 1204,
  "by_reason": {
    "unsubscribed": 1130,
    "bounced": 61,
    "complained": 9,
    "deleted": 4
  }
}

{
  "error": "email must be a valid email address"
}

POST /api/v1/suppressions

Import suppressions (JSON or CSV). Puts addresses on the workspace's suppression list so they are never emailed. Use it first when migrating: load the old platform's unsubscribes, bounces and complaints before importing contacts or sending. Send either a JSON body (`entries`, at most 5,000 per request) or `multipart/form-data` with a CSV in `file` (at most 5 MB; header row with `email` and optional `reason`, or one bare address per line). Each entry's `reason` is `unsubscribed`, `bounced` or `complained`; blank means the request-level default `reason` (itself defaulting to `unsubscribed`). Common spellings from other platforms are accepted: `cleaned`, `hard bounce`, `invalid` → `bounced`; `cancelled`, `canceled`, `opted out` → `unsubscribed`; `junk`, `spam`, `abuse`, `complaint` → `complained`. `deleted` cannot be imported. A stronger reason (complained > bounced > unsubscribed > deleted) replaces a weaker one; a weaker one never downgrades. Repeated addresses in one request are folded together and the extra rows counted as `unchanged`, so `received = added + upgraded + unchanged + invalid`. Rows with a malformed address (or over 254 characters) or an unknown reason are counted as `invalid` and skipped. Existing contacts with a matching address whose status is still `subscribed` are switched to the imported status with `unsubscribed_at` set to now (`contacts_updated`); contacts that are already unsubscribed, bounced or complained are left as they are. No contact is ever created. Work is batched 200 addresses at a time; a database failure part-way returns `500` and the earlier batches stay written, so the request is safe to repeat. Requires `contacts:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/suppressions" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "unsubscribed",
  "entries": [
    "jane@example.com"
  ]
}'

Responses

{
  "received": 3,
  "added": 2,
  "upgraded": 1,
  "unchanged": 0,
  "invalid": 0,
  "contacts_updated": 1,
  "by_reason": {
    "unsubscribed": 1,
    "bounced": 1,
    "complained": 1
  }
}

{
  "error": "entries array is required"
}

{
  "error": "The file is too large. Uploads are limited to 5 MB — split the CSV and import it in parts."
}

{
  "error": "No rows found. The CSV needs an \"email\" column header (optionally \"reason\") and at least one data row.",
  "invalid": 0
}

{
  "error": "Failed to import suppressions",
  "details": "connection reset"
}

GET /api/v1/suppressions/list

Browse the suppression list. A page of the suppression list, newest first. Each row carries the reason, when it was added, where it came from (`source`), a masked display form of the address (`j***@example.com`) and its domain — stored on rows written since 2026-09-14, derived at read time from a contact row that still carries the address for older rows, and null for the rest (older hash-only rows and erasures; those are never back-filled). `contact` is that still-existing contact, when there is one: the only place the full address appears. `liftable` says whether `POST /api/v1/suppressions/lift` would accept the row. `details_available` is false while the workspace's database is missing the display columns (every detail is then null and `domain` is ignored). Requires `contacts:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/suppressions/list?page=1&limit=50" \
  -H "x-api-key: sb_live_…"

Responses

{
  "suppressions": [
    {
      "email_hash": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
      "reason": "bounced",
      "source": "provider",
      "created_at": "2026-09-14T09:12:41.000Z",
      "email_masked": "j***@example.com",
      "email_domain": "example.com",
      "contact": {
        "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
        "email": "jane@example.com",
        "status": "bounced"
      },
      "liftable": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  },
  "details_available": true
}

{
  "error": "reason must be unsubscribed, bounced, complained or deleted"
}

GET /api/v1/suppressions/export

Export the suppression list as CSV. The whole list (or one reason / domain) as a CSV download, newest first. Columns: `email` (filled only where a contact row still carries the address), `email_masked`, `domain`, `reason`, `source`, `added_at`, `contact_id`. Every cell is quoted and formula-safe, like the contacts export. Requires `contacts:export`, the same grant as the contacts export; the paged list and the counts stay on `contacts:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/suppressions/export?reason=unsubscribed&domain=string" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Contact not found"
}

{
  "error": "Forbidden: contacts:export permission required"
}

POST /api/v1/suppressions/lift

Lift the block a deleted contact left. Takes a `deleted` suppression off the list so the address can be re-added by an import, the API or a signup form. Refused with `409` for a bounce or a complaint (permanent), an unsubscribe (that needs the person's new consent — re-subscribe the contact, or `resubscribe: true`), and an erasure (the person asked to be forgotten; only they can return, through a form). Identify the row by `email` or by the `email_hash` from the list. Session callers must hold the workspace admin role (`403` otherwise); an API key needs `contacts:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/suppressions/lift" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane@example.com",
  "email_hash": "string"
}'

Responses

{
  "lifted": true,
  "reason": "deleted"
}

{
  "error": "email or email_hash is required"
}

{
  "error": "Only a workspace admin can lift a block. Ask a workspace admin, or ask to be given the admin role under Settings → Team."
}

{
  "error": "This address is not on the suppression list."
}

{
  "error": "This address previously bounced and cannot be re-added.",
  "reason": "bounced"
}

POST /api/v1/imports/connect

Check a platform API key and list what it can import. Validates a Mailchimp, MailerLite, Kit, Brevo or EmailOctopus API key with one cheap call and returns the account, the lists it can see (Mailchimp audiences, MailerLite groups, Kit tags, Brevo lists, EmailOctopus lists — MailerLite and Kit also offer an "All subscribers" entry with id `""`) with subscriber counts, and the source's capabilities (what comes across: opt-in dates, consent evidence, bounces, complaints, tags, custom fields; plus notes and limitations). Credentials are used for this request only: never stored, never logged, never echoed. For Mailchimp the data centre is read from the key's `-usNN` suffix (pass `credentials.dc` if your key has none). Requires `contacts:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/imports/connect" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "mailchimp",
  "credentials": {
    "api_key": "string",
    "dc": "string"
  }
}'

Responses

{
  "ok": true,
  "source": "mailchimp",
  "label": "Mailchimp",
  "account": {
    "name": "Acme Newsletter",
    "email": "jane@acme.example"
  },
  "lists": [
    {
      "id": "a1b2c3d4e5",
      "name": "Newsletter",
      "member_count": 1180,
      "suppressed_count": 42,
      "kind": "audience"
    }
  ],
  "requires_list": true,
  "capabilities": {
    "platform": "mailchimp",
    "label": "Mailchimp",
    "provides": {
      "subscribed_at": true,
      "consent_ip": true,
      "consent_timestamp": true,
      "consent_source": true,
      "bounces": true,
      "complaints": false,
      "unsubscribes": true,
      "tags": true,
      "custom_fields": true
    },
    "notes": [
      "\"cleaned\" members are imported as bounced."
    ],
    "limitations": [
      "No complaint (spam report) status is exposed on members."
    ]
  },
  "subrequests": 2
}

{
  "error": "Contact not found"
}

{
  "ok": false,
  "error": "Kit request failed: GET https://api.kit.com/v4/account: HTTP 503"
}

POST /api/v1/imports/run

Import contacts from a platform. Streams the platform's subscribers into the workspace: each source page is normalised, its unsubscribed / bounced / complained addresses are written to the suppression list **first**, then the page goes through the same write path as the CSV importer (contacts, tags, custom fields, optional list membership, `contact_created` and `list_joined` automations). Status mapping — Mailchimp `cleaned` → bounced, `pending` → not imported, `archived`/`transactional` → skipped (`skipped_other`); MailerLite `junk` → complained, `unconfirmed` → not imported; Kit `cancelled` → unsubscribed, `inactive` → not imported. Consent evidence becomes the custom fields `consent_ip`, `consent_confirmed_at`, `consent_source` where the platform exposes it. Caps per run: 25,000 contacts written (rounded up to the end of the source page in progress), plus a request budget and a time budget. When a cap is hit, or the plan has no room for the next page of subscribed contacts, the run stops between pages and returns `truncated: true`, `stop_reason` (`max_contacts`, `subrequests`, `time`, `contact_limit`) and `next_hint` with a `cursor`; pass it back as `options.cursor` (with the same `source` and `list_ids`) to continue from that page. Re-runs are idempotent: existing contacts are skipped (`skipped_duplicates`), tags and fields are additive, a suppressed status always wins over subscribed and a stronger suppression reason never downgrades. Kit: tags and signup attribution arrive with each subscriber (`include=tags,attribution`), so any number of tags is mapped in one pass. Mailchimp: members with more than 50 tags have their full tag set fetched separately (a bounded number of such lookups per run; the rest are counted in `tags_truncated`). Brevo: a blacklisted contact costs one extra call to tell a bounce, a complaint and an unsubscribe apart (a bounded number of such lookups per run; the rest are recorded as unsubscribed). `list_ids` are audience ids (Mailchimp, required), group ids (MailerLite), tag ids (Kit), list ids (Brevo), or list ids (EmailOctopus, required); an empty id or no `list_ids` means all subscribers for MailerLite, Kit and Brevo. Credentials are used for this request only and never stored or logged. Requires `contacts:write`.

Request body

See the OpenAPI document for the body schema.

Example request

curl -X POST "https://sendbeam.io/api/v1/imports/run" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d 'null'

Responses

{
  "ok": true,
  "source": "mailchimp",
  "imported": 1102,
  "updated": 3,
  "skipped_duplicates": 3,
  "suppressed": 42,
  "skipped_unconfirmed": 11,
  "skipped_other": 2,
  "skipped_suppressed": 0,
  "invalid": 1,
  "tags_created": 4,
  "tags_attached": 1580,
  "tags_skipped": false,
  "tags_truncated": 0,
  "custom_field_keys": [
    "company",
    "consent_ip",
    "consent_confirmed_at",
    "consent_source"
  ],
  "list_added": 1102,
  "list_pending_confirmation": 0,
  "contacts_read": 1161,
  "contacts_written": 1147,
  "pages": 2,
  "subrequests": 2,
  "db_requests": 31,
  "duration_ms": 6120,
  "truncated": false,
  "stop_reason": null,
  "next_hint": null,
  "capabilities": {
    "platform": "mailchimp"
  }
}

{
  "error": "list_ids is required for Mailchimp: pass at least one list id from /api/v1/imports/connect"
}

{
  "error": "List not found"
}

{
  "error": "Failed to import contacts",
  "details": "connection reset"
}

{
  "error": "MailerLite request failed: GET https://connect.mailerlite.com/api/subscribers: HTTP 500"
}

GET /api/v1/tags

List tags. Returns all tags in the workspace sorted by name. Requires `tags:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/tags" \
  -H "x-api-key: sb_live_…"

Responses

{
  "tags": [
    {
      "id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "Customer",
      "color": "#2563EB",
      "created_at": "2026-08-20T09:00:00.000Z"
    }
  ]
}

POST /api/v1/tags

Create a tag. Creates a tag. Names are unique per workspace. `color` defaults to `#6B7280`. Requires `tags:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/tags" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Customer",
  "color": "#2563EB"
}'

Responses

{
  "tag": {
    "id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Customer",
    "color": "#2563EB",
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

{
  "error": "name is required"
}

{
  "error": "A tag with this name already exists"
}

GET /api/v1/tags/{id}

Get a tag. Returns one tag with `contact_count`, the number of contacts carrying it. Requires `tags:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/tags/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "tag": null
}

{
  "error": "Tag not found"
}

PATCH /api/v1/tags/{id}

Update a tag. Renames or recolours a tag. Empty strings are ignored. Requires `tags:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/tags/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP customer"
}'

Responses

{
  "tag": {
    "id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Customer",
    "color": "#2563EB",
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

{
  "error": "Tag not found"
}

{
  "error": "A tag with this name already exists"
}

DELETE /api/v1/tags/{id}

Delete a tag. Deletes the tag and removes it from every contact. Requires `tags:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/tags/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Tag not found"
}

GET /api/v1/lists

List lists. Returns every list in the workspace, newest first. Requires `lists:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/lists" \
  -H "x-api-key: sb_live_…"

Responses

{
  "lists": [
    {
      "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "Newsletter",
      "description": "Weekly product updates",
      "double_optin": false,
      "offerable_across_account": false,
      "created_at": "2026-08-20T09:00:00.000Z"
    }
  ]
}

POST /api/v1/lists

Create a list. Creates a list. Names are unique per workspace. Set `double_optin: true` to require email confirmation before members are mailed (Free-plan workspaces are double opt-in on every list regardless). Requires `lists:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/lists" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Newsletter",
  "description": "Weekly product updates",
  "double_optin": false
}'

Responses

{
  "list": {
    "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Newsletter",
    "description": "Weekly product updates",
    "double_optin": false,
    "offerable_across_account": false,
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

{
  "error": "name is required"
}

{
  "error": "A list with this name already exists"
}

GET /api/v1/lists/{id}

Get a list. Returns one list with its member count. Requires `lists:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/lists/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "list": null
}

PATCH /api/v1/lists/{id}

Update a list. Renames a list, changes its description (an empty `description` clears it; an empty `name` is ignored), switches double opt-in on or off (a change to `double_optin` only affects people who join from then on), or marks the list offerable to people who subscribed on your other workspaces (`offerable_across_account` — see the List schema for what that does and does not do). Requires `lists:write`. `offerable_across_account` needs more than the scope: only a signed-in workspace admin of a workspace that belongs to an account may change it, so a request carrying it from an API key, a member seat or a workspace with no account is refused with `403` and nothing else in the body is applied.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/lists/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Monthly digest",
  "double_optin": true
}'

Responses

{
  "list": {
    "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Newsletter",
    "description": "Weekly product updates",
    "double_optin": false,
    "offerable_across_account": false,
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

{
  "error": "A list with this name already exists"
}

DELETE /api/v1/lists/{id}

Delete a list. Deletes the list and its memberships. Contacts themselves are kept. Requires `lists:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/lists/id" \
  -H "x-api-key: sb_live_…"

Responses

GET /api/v1/lists/{id}/contacts

List members of a list. Returns the contacts in a list, most recently added first, with pagination. Each contact carries `added_at`. Requires `lists:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/lists/id/contacts?page=1&limit=50" \
  -H "x-api-key: sb_live_…"

Responses

{
  "contacts": [
    null
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "total_pages": 25
  }
}

POST /api/v1/lists/{id}/contacts

Add a contact to a list. Adds an existing `subscribed` contact to the list. On a double opt-in list — or in a Free-plan workspace, where every list is double opt-in — the membership is created unconfirmed (`membership: "pending_confirmation"`, `confirmed: false`) and the contact is emailed a confirmation link; campaigns to the list skip them until they click it, and `list_joined` automations enrol them at that point. Otherwise the membership is confirmed immediately (`membership: "confirmed"`) and `list_joined` automations targeting this list (or any list) enrol the contact now. `double_optin_sent` says whether a confirmation email went out on this request: confirmations to one address are throttled, so a pending membership can come back with `double_optin_sent: false`. Posting the same contact again while they are still unconfirmed sends the confirmation again (subject to that throttle) and returns `200` with `already_member: true`; a contact who is already a confirmed member is a `409`. A contact whose status is not `subscribed` is refused with `422`. Requires `lists:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/lists/id/contacts" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
}'

Responses

{
  "list_contact": {
    "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "contact_id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "created_at": "2026-09-01T10:10:00.000Z",
    "confirmed": false
  },
  "double_optin_sent": true,
  "membership": "pending_confirmation",
  "already_member": true
}

{
  "list_contact": {
    "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "contact_id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "created_at": "2026-09-01T10:10:00.000Z",
    "confirmed": true
  },
  "double_optin_sent": true,
  "membership": "confirmed",
  "already_member": true
}

{
  "error": "contact_id is required"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact is already in this list"
}

{
  "error": "Cannot add a contact with status: unsubscribed. Only subscribed contacts can be added to a list."
}

DELETE /api/v1/lists/{id}/contacts

Remove a contact from a list. Removes the contact from the list. The contact ID is sent in the JSON body. Requires `lists:write`.

Request body

Example request

curl -X DELETE "https://sendbeam.io/api/v1/lists/id/contacts" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}'

Responses

{
  "error": "contact_id is required"
}

{
  "error": "Contact is not in this list"
}

POST /api/v1/lists/{id}/confirmations

Send confirmation emails to pending members. Sends (or re-sends) the double opt-in confirmation email to members of the list who have not confirmed yet — the deliberate counterpart of a bulk add or an import, which never send one. Only unconfirmed memberships are read, and the token is written only while the row is still unconfirmed, so a member who has already clicked can never be mailed by this. A member emailed anything in the last 24 hours is skipped (`skipped_recent`), a member no longer `subscribed` is skipped (`skipped_not_subscribed`), at most 500 are mailed per request (`remaining` says how many are left; `stopped: "cap"`), and five consecutive provider refusals stop the run (`stopped: "send_failures"` — plan quota, paused workspace, sender problem). Pass `contact_ids` to limit the run to some members. Each email counts against the monthly allowance. Requires `lists:write`.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/lists/id/confirmations" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_ids": [
    "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  ]
}'

Responses

{
  "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "pending": 12,
  "sent": 10,
  "skipped_recent": 2,
  "skipped_not_subscribed": 0,
  "failed": 0,
  "remaining": 0,
  "cap": 500,
  "stopped": null
}

{
  "error": "contact_ids must be an array of contact ids"
}

{
  "error": "This list does not use double opt-in, so there is nothing to confirm."
}

GET /api/v1/segments

List segments. Returns every segment, newest first, each with a live `contact_count` (raw rule match) and `reachable_count` (the subscribed subset a campaign could actually reach). Requires `segments:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/segments" \
  -H "x-api-key: sb_live_…"

Responses

{
  "segments": [
    null
  ]
}

POST /api/v1/segments

Create a segment. Saves a named rule set. All rules must match (AND). Requires `segments:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/segments" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "London customers",
  "rules": [
    {
      "field": "custom_fields.region",
      "operator": "equals",
      "value": "London"
    },
    {
      "field": "status",
      "operator": "equals",
      "value": "subscribed"
    }
  ]
}'

Responses

{
  "segment": {
    "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "London customers",
    "rules": [
      {
        "field": "custom_fields.region",
        "operator": "equals",
        "value": "London"
      }
    ],
    "created_at": "2026-08-25T12:00:00.000Z"
  }
}

GET /api/v1/segments/{id}

Get a segment. Returns one segment with the same live `contact_count` and `reachable_count` the list endpoint computes. Requires `segments:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/segments/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "segment": null
}

{
  "error": "Segment not found"
}

PATCH /api/v1/segments/{id}

Update a segment. Renames a segment and/or replaces its rules. An empty `rules` array is ignored. Requires `segments:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/segments/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "rules": [
    {
      "field": "custom_fields.region",
      "operator": "equals",
      "value": "London"
    }
  ]
}'

Responses

{
  "segment": {
    "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "London customers",
    "rules": [
      {
        "field": "custom_fields.region",
        "operator": "equals",
        "value": "London"
      }
    ],
    "created_at": "2026-08-25T12:00:00.000Z"
  }
}

{
  "error": "Segment not found"
}

DELETE /api/v1/segments/{id}

Delete a segment. Deletes the segment. Returns `204` with no body. Requires `segments:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/segments/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Segment not found"
}

POST /api/v1/segments/preview

Preview rules before saving. Counts the contacts matching an ad-hoc rule set and returns up to 5 sample contacts. A read: it is exempt from the Pro-plan write gate. Requires `segments:read`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/segments/preview" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "field": "email",
      "operator": "contains",
      "value": "@example.com"
    }
  ]
}'

Responses

GET /api/v1/segments/{id}/preview

Preview a saved segment. Counts the contacts matching a saved segment and returns up to 5 sample contacts. Requires `segments:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/segments/id/preview" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Segment not found"
}

GET /api/v1/campaigns

List campaigns. Returns campaigns, newest first, with pagination. Optionally filter by status. Requires `campaigns:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/campaigns?page=1&limit=50" \
  -H "x-api-key: sb_live_…"

Responses

{
  "campaigns": [
    {
      "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "September newsletter",
      "subject": "What's new this month",
      "from_name": "Acme",
      "from_email": "hello@acme.com",
      "html_content": "<h1>Hello {{first_name}}</h1>",
      "text_content": "Hello {{first_name}}",
      "status": "draft",
      "send_to_type": "list",
      "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "scheduled_at": null,
      "sent_at": null,
      "stats_sent": 0,
      "stats_delivered": 0,
      "stats_opened": 0,
      "stats_clicked": 0,
      "stats_bounced": 0,
      "stats_unsubscribed": 0,
      "created_at": "2026-09-01T11:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "total_pages": 25
  }
}

POST /api/v1/campaigns

Create a campaign. Creates a draft campaign. `send_to_type` chooses the audience: `all` (every subscribed contact), `list` or `segment` (then `send_to_id` must reference one this workspace owns). A draft may be created without a `subject` (the campaign wizard saves as soon as there is a name); the send endpoint refuses a campaign whose subject is still empty. `html_content` is limited to 500,000 characters and `text_content` to 200,000 (`413`). Send a `draft_key` of your own (a UUID) to make the create idempotent: a second create with the same key returns the existing draft with `200` instead of making another. Nothing is sent until you call the send endpoint. Requires `campaigns:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "draft_key": "string",
  "language": "en",
  "languages": {
    "fr": {
      "subject": "Nouveautés de septembre",
      "html_content": "<p>Bonjour…</p>"
    }
  },
  "subject_b": "string",
  "send_pace_hours": null,
  "send_at_best_time": true,
  "ab_test": {
    "sample_pct": 20,
    "wait_minutes": 120,
    "metric": "opens",
    "test_on": "subject",
    "variants": [
      {
        "subject": "string",
        "from_name": "string",
        "html_content": "string",
        "text_content": "string",
        "blocks": [],
        "send_offset_minutes": 60
      }
    ]
  },
  "name": "September newsletter",
  "subject": "What'\''s new this month",
  "from_name": "Acme",
  "from_email": "hello@acme.com",
  "html_content": "<h1>Hello {{first_name}}</h1>",
  "text_content": "Hello {{first_name}}",
  "blocks": [
    {
      "id": "block_1",
      "type": "text",
      "props": {
        "heading": "This month",
        "text": "Hi {{first_name|there}},",
        "padding": 24
      }
    }
  ],
  "send_to_type": "all",
  "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}'

Responses

{
  "campaign": {
    "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "September newsletter",
    "subject": "What's new this month",
    "from_name": "Acme",
    "from_email": "hello@acme.com",
    "html_content": "<h1>Hello {{first_name}}</h1>",
    "text_content": "Hello {{first_name}}",
    "status": "draft",
    "send_to_type": "list",
    "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "scheduled_at": null,
    "sent_at": null,
    "stats_sent": 0,
    "stats_delivered": 0,
    "stats_opened": 0,
    "stats_clicked": 0,
    "stats_bounced": 0,
    "stats_unsubscribed": 0,
    "created_at": "2026-09-01T11:00:00.000Z"
  },
  "existing": true
}

{
  "campaign": {
    "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "September newsletter",
    "subject": "What's new this month",
    "from_name": "Acme",
    "from_email": "hello@acme.com",
    "html_content": "<h1>Hello {{first_name}}</h1>",
    "text_content": "Hello {{first_name}}",
    "status": "draft",
    "send_to_type": "list",
    "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "scheduled_at": null,
    "sent_at": null,
    "stats_sent": 0,
    "stats_delivered": 0,
    "stats_opened": 0,
    "stats_clicked": 0,
    "stats_bounced": 0,
    "stats_unsubscribed": 0,
    "created_at": "2026-09-01T11:00:00.000Z"
  }
}

{
  "error": "Campaign name is required."
}

{
  "error": "Failed to create campaign."
}

GET /api/v1/campaigns/{id}

Get a campaign. Returns one campaign with a `stats` object computed from its per-recipient send records. Requires `campaigns:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/campaigns/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "campaign": null
}

PATCH /api/v1/campaigns/{id}

Update a campaign. Updates a `draft` or `scheduled` campaign. Only the listed fields are accepted; others are ignored. `name` may not be emptied; `subject` may be empty on a draft but not on a scheduled campaign. When `send_to_type` is `list` or `segment`, `send_to_id` must be supplied in the same request and belong to this workspace. `blocks` (the visual builder's block JSON) is stored when sent; sending new `html_content` without `blocks` clears them. To avoid overwriting a concurrent edit, send `expected_updated_at` — the `updated_at` you last read; if the campaign has changed since, nothing is written and the answer is `409` with `code: "stale"` and the current `updated_at`. Requires `campaigns:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/campaigns/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "What'\''s new in September",
  "send_to_type": "all",
  "send_to_id": null
}'

Responses

{
  "campaign": {
    "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "September newsletter",
    "subject": "What's new this month",
    "from_name": "Acme",
    "from_email": "hello@acme.com",
    "html_content": "<h1>Hello {{first_name}}</h1>",
    "text_content": "Hello {{first_name}}",
    "status": "draft",
    "send_to_type": "list",
    "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "scheduled_at": null,
    "sent_at": null,
    "stats_sent": 0,
    "stats_delivered": 0,
    "stats_opened": 0,
    "stats_clicked": 0,
    "stats_bounced": 0,
    "stats_unsubscribed": 0,
    "created_at": "2026-09-01T11:00:00.000Z"
  }
}

{
  "error": "Contact not found"
}

{
  "error": "Campaign not found."
}

{
  "error": "string",
  "code": "stale",
  "updated_at": "2026-09-02T12:00:00Z"
}

{
  "error": "Failed to update campaign."
}

DELETE /api/v1/campaigns/{id}

Delete a draft or cancelled campaign. Removes a campaign that never went out. Sent and sending campaigns are kept as records (`409`); cancel a scheduled campaign first. Requires `campaigns:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/campaigns/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Campaign not found"
}

{
  "error": "Only draft or cancelled campaigns can be deleted; this one is sent."
}

POST /api/v1/campaigns/{id}/send

Send or schedule a campaign. With a `scheduled_at` in the future the campaign becomes `scheduled` and is sent by the scheduler at that time (200). Without a body (or without `scheduled_at`) the audience is resolved now — subscribed contacts only; on a double opt-in list only confirmed members; on the Free plan only contacts who have confirmed a subscription, whatever the audience — the plan's monthly email quota is checked for the whole audience, recipients are queued and the campaign becomes `sending` (202). Delivery drains in the background, fairly across every sending campaign and within the plan's hourly ceiling (what does not fit waits for the next hour); the workspace's sender address is re-validated on every send, rows that cannot be sent are recorded as failed with the reason, and the campaign flips to `sent` when the queue is empty. Only `draft` or `scheduled` campaigns can be sent. `GET /api/v1/campaigns/{id}/audience` returns the recipient count and the plan check the send will apply, without sending. Requires `campaigns:send` — authoring a campaign (`campaigns:write`) does not permit mailing its audience.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/id/send" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduled_at": "2026-09-10T09:00:00Z"
}'

Responses

{
  "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "status": "scheduled",
  "scheduled_at": "2026-09-10T09:00:00.000Z"
}

{
  "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "status": "sending",
  "queued": 1834,
  "skipped_placeholder": 0
}

{
  "error": "No subscribed contacts found for this audience."
}

{
  "error": "Contact not found"
}

{
  "error": "Cannot send a campaign with status 'sent'."
}

{
  "error": "Failed to create send queue."
}

GET /api/v1/campaigns/{id}/audience

Preview a campaign's audience. Returns how many contacts the campaign would reach if it were sent now, computed by exactly the resolver the send endpoint and the scheduler use: `subscribed` contacts only; on a double opt-in list only confirmed members; on the Free plan only contacts who have confirmed a subscription, whatever the audience. `can_send` says whether `POST /api/v1/campaigns/{id}/send` would be accepted right now (campaign is `draft` or `scheduled`, at least one recipient, sending not paused, and the audience fits the plan's remaining monthly email quota); when it is false, `reason` is the message the send would fail with. `placeholders` names subscribed contacts that can never receive mail — addresses on `example.com` / `.net` / `.org`, on a reserved `.test`, `.invalid`, `.localhost` or `.example` domain, or `abuse@` / `postmaster@`. The send leaves them out (the same rule the import applies), so they are not in `recipients`; they are named so they can be archived or deleted. `placeholder_count` is the total when more than twenty are named. Nothing is changed and nothing is sent. The audience is resolved again at send time, so a count taken earlier can differ if contacts join, leave, unsubscribe or confirm in between. Requires `campaigns:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/campaigns/id/audience" \
  -H "x-api-key: sb_live_…"

Responses

{
  "audience": {
    "send_to_type": "all",
    "send_to_id": null,
    "recipients": 1
  },
  "can_send": true,
  "reason": "string",
  "placeholders": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "email": "string",
      "kind": "example_domain",
      "reason": "string"
    }
  ],
  "placeholder_count": 1
}

POST /api/v1/campaigns/{id}/test

Send a test copy. Sends the campaign as a test — to the signed-in person by default, or to `to` (a list of addresses, or one comma-separated string), each copy with `[Test]` in front of the subject, the same From, merge tags and footer as the real send, and a working view-in-browser link. With `contact_id` (a contact of this workspace) the merge tags are rendered with that contact's name, email and custom fields while the copies still go to `to`; the unsubscribe link in a test is bound to the test, never to a real contact. Test copies are not written to the sends ledger, do not count against the plan and do not appear in the campaign's stats. The number of addresses per test is capped per plan, and there is an hourly allowance of test emails per workspace. Session only: the default recipient is the signed-in person, so an API key gets `400`. Requires `campaigns:write` (and `contacts:read` with `contact_id`).

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/id/test" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "jane@example.com"
  ],
  "contact_id": null,
  "language": null
}'

Responses

{
  "ok": true,
  "to": [
    "me@acme.com",
    "colleague@acme.com"
  ],
  "failed": [],
  "subject": "[Test] What's new this month",
  "rendered_as": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "email": "jane@client.com"
  },
  "warnings": []
}

{
  "error": "colleague@ is not a valid email address"
}

{
  "error": "Contact not found."
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

POST /api/v1/campaigns/preview

Render an email for one contact. Resolves the merge tags in `subject`, `html` and `text` exactly as a send would, for the contact named by `contact_id` (one of this workspace's) or, without one, for a stand-in built from the signed-in person (empty fields for an API key). `{{web_version_url}}` becomes the campaign's plain web-version page when `campaign_id` is given; `{{unsubscribe_url}}` is a dead link — a preview can never act on the contact. Conditional blocks (`{{#if custom_fields.plan is "pro"}}…{{else}}…{{/if}}`) in `html` and `text` are evaluated for that contact; a subject line never carries one and is returned with its block tags as typed. Nothing is stored or sent. Same size caps as campaign creation (`413`). Requires `campaigns:read`, plus `contacts:read` with `contact_id`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/preview" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "string",
  "html": "string",
  "text": "string",
  "contact_id": null,
  "campaign_id": null
}'

Responses

{
  "subject": "Hi Jane",
  "html": "<p>Your plan: Gold</p>",
  "text": "",
  "rendered_as": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "email": "jane@client.com",
    "name": "Jane Doe"
  }
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found."
}

POST /api/v1/campaigns/audience

Preview an audience before saving a campaign. The same answer as `GET /api/v1/campaigns/{id}/audience` for an audience that is not saved yet: send `send_to_type` (`all`, `list` or `segment`) and, for a list or segment, its `send_to_id`. The campaign wizard's Review step calls this before the draft exists. `can_send` is evaluated as for a draft. Nothing is changed and nothing is sent. Requires `campaigns:read`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/audience" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "send_to_type": "list",
  "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}'

Responses

{
  "audience": {
    "send_to_type": "all",
    "send_to_id": null,
    "recipients": 1
  },
  "can_send": true,
  "reason": "string",
  "placeholders": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "email": "string",
      "kind": "example_domain",
      "reason": "string"
    }
  ],
  "placeholder_count": 1
}

{
  "error": "send_to_id is required for a list audience"
}

POST /api/v1/campaigns/{id}/cancel

Cancel a scheduled campaign, or stop one that is sending. Moves a `scheduled` campaign to `cancelled` so it will not be sent. A `sending` campaign — one going out over a day at each contact's best time, or a send-time test with a version still to come — is stopped instead: the recipients not yet sent are removed, `status_reason` records how many, and the campaign completes as `sent` within the minute (the response carries `status: sending` and `stopped`). Campaigns in any other state answer `409`. Requires `campaigns:write`.

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/id/cancel" \
  -H "x-api-key: sb_live_…"

Responses

{
  "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "status": "cancelled"
}

{
  "error": "Only scheduled campaigns can be cancelled. This campaign has status 'draft'."
}

{
  "error": "Failed to cancel campaign."
}

POST /api/v1/campaigns/subject-ideas

Suggest subject lines. Five alternative subject lines written from the current subject and the email's text (the first ~1,500 characters, merge tags removed). Nothing is stored. There is a daily allowance per workspace. `503` when the installation has no suggestion service configured. Requires `campaigns:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/subject-ideas" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "string",
  "html_content": "string",
  "audience": "string"
}'

Responses

{
  "ideas": [
    {
      "subject": "Three things you asked for, now live",
      "why": "direct, names the payoff"
    }
  ]
}

{
  "error": "Give a subject or some email content to work from."
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

GET /api/v1/campaigns/{id}/report

Links clicked, email clients and poll answers. Per-link click counts (`clicks` = every click, `unique` = distinct recipients), the email clients and devices behind the human opens, and the answers to any poll block in the email, all from the tracked open and click events. Machine opens and clicks (link scanners, mail-client prefetchers) are excluded. Gmail and Yahoo proxy images, so their device is reported as `Unknown`. `polls` holds one entry per poll block, in the email's order — its `id` is the block's, `question` and the option `label`s come from the campaign's block JSON (a blank question and `Option n` labels when the campaign has none) — with a `count` per option and `answers`, the number of recipients who answered. One answer per recipient: a person who clicks twice is counted once, for their latest click. Poll answers count in the top-level `clicks` but are not listed under `links`. `revenue` — the orders your store sent to SendBeam that were attributed to this campaign (see /docs/ecommerce/revenue) — is present only when there is at least one such order: a campaign that earned nothing and a campaign whose store sends no orders are different answers. Requires `campaigns:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/campaigns/id/report" \
  -H "x-api-key: sb_live_…"

Responses

{
  "campaign_id": "2f9c1b1e-3f9e-4a3b-9c2f-1d1e2f3a4b5c",
  "links": [
    {
      "url": "https://example.com/post",
      "clicks": 41,
      "unique": 33
    }
  ],
  "clients": [
    {
      "name": "Gmail",
      "count": 120
    },
    {
      "name": "Apple Mail",
      "count": 64
    }
  ],
  "devices": [
    {
      "name": "Unknown",
      "count": 120
    },
    {
      "name": "Mobile",
      "count": 50
    },
    {
      "name": "Desktop",
      "count": 14
    }
  ],
  "opens": 184,
  "clicks": 63,
  "polls": [
    {
      "id": "block_1758540000000_k3j9x2",
      "question": "How useful was this email?",
      "answers": 22,
      "options": [
        {
          "index": 1,
          "label": "Very useful",
          "count": 14
        },
        {
          "index": 2,
          "label": "Somewhat",
          "count": 6
        },
        {
          "index": 3,
          "label": "Not really",
          "count": 2
        }
      ]
    }
  ],
  "revenue": {
    "orders": 12,
    "total": 1240.5,
    "currency": "GBP",
    "by_currency": [
      {
        "currency": "GBP",
        "total": 1240.5,
        "orders": 12
      }
    ]
  }
}

{
  "error": "Campaign not found"
}

GET /api/v1/campaigns/{id}/ab-test

A/B test state and live counts. The test settings and state stored on the campaign, what it varies (`test_on`), each version (`versions[]`: `letter`, `label`, and the `subject`, `from_name`, or `send_offset_minutes` + `release_at` it tests) and live per-version counts from the send queue (`live.a`, `live.b`, … : `sent`, `opened`, `clicked`, and — once an order your store sent in has been attributed to that version — `revenue`, `orders`, `currency`). Requires `campaigns:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/campaigns/id/ab-test" \
  -H "x-api-key: sb_live_…"

Responses

{
  "ab_test": {},
  "test_on": "subject",
  "subject": "string",
  "subject_b": "string",
  "versions": [
    {
      "letter": "a",
      "label": "string",
      "subject": "string",
      "from_name": "string"
    }
  ],
  "live": {}
}

{
  "error": "This campaign has no A/B test"
}

POST /api/v1/campaigns/{id}/ab-test

End an A/B test now. Settles a running test straight away: with `{"winner": "a" | "b" | … }` that version goes to the remaining recipients (it must be one of the versions the test sent); with no body the version with the better rate on the test's metric wins — opens or clicks per recipient, or for a `revenue` test the most attributed revenue per recipient (ties, including no orders at all, go to the earlier letter). The queue worker does the same automatically once `decide_at` passes. Requires `campaigns:write`.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/id/ab-test" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "winner": "a"
}'

Responses

{
  "ab_test": {}
}

{
  "error": "winner must be one of \"a\", \"b\", \"c\", \"d\", \"e\""
}

{
  "error": "Campaign not found"
}

{
  "error": "This campaign is not running an A/B test"
}

POST /api/v1/campaigns/{id}/duplicate

Duplicate a campaign. Creates a new draft copying the content and audience of an existing campaign. The copy is named `<original name> (Copy)`. With the optional body `{"audience": "non_openers"}` on a sent campaign, the copy is named `<original name> (Send again to non-openers)` and its audience is a segment called `Did not open: <original name>` with the single rule `campaign not_opened <id>` — the people the original reached who have not opened it, re-evaluated at send time; the segment is reused when the same campaign is sent again later. Requires `campaigns:write`.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/campaigns/id/duplicate" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "audience": "non_openers"
}'

Responses

{
  "campaign": {
    "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "September newsletter",
    "subject": "What's new this month",
    "from_name": "Acme",
    "from_email": "hello@acme.com",
    "html_content": "<h1>Hello {{first_name}}</h1>",
    "text_content": "Hello {{first_name}}",
    "status": "draft",
    "send_to_type": "list",
    "send_to_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "scheduled_at": null,
    "sent_at": null,
    "stats_sent": 0,
    "stats_delivered": 0,
    "stats_opened": 0,
    "stats_clicked": 0,
    "stats_bounced": 0,
    "stats_unsubscribed": 0,
    "created_at": "2026-09-01T11:00:00.000Z"
  }
}

{
  "error": "Only a sent campaign has non-openers to send to again"
}

{
  "error": "Campaign not found"
}

{
  "error": "Failed to duplicate campaign"
}

POST /api/v1/ai/email-draft

Draft an email from a brief. A subject line and a list of builder blocks written from the brief — the same `blocks` shape a campaign or template takes — for the editor to load and a person to edit. The prompt carries the brief and the workspace's custom-field names only; nothing is sent or saved. Behind the ai-assist flag (`404` when it is off for the workspace). A daily allowance per workspace is shared by the assistants (`429`). Requires `campaigns:write` or `templates:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/ai/email-draft" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "brief": "string"
}'

Responses

{
  "subject": "string",
  "name": "string",
  "blocks": [
    {
      "id": "block_1",
      "type": "text",
      "props": {
        "heading": "This month",
        "text": "Hi {{first_name|there}},",
        "padding": 24
      }
    }
  ],
  "warnings": [
    "string"
  ],
  "model": "string"
}

{
  "error": "Describe the email you want: who it is for, what it says, and what the reader should do."
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

POST /api/v1/ai/automation-draft

Draft an automation from a brief. A recipe — the same shape the recipe gallery uses: a trigger, a linear sequence of send_email / wait / add_tag / remove_tag steps, and a placeholder for every list, form or tag the draft names — for a person to resolve and import. Nothing is created here. Behind the ai-assist flag (`404` when off); the assistants' shared daily allowance (`429`). Requires `automations:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/ai/automation-draft" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "brief": "string"
}'

Responses

{
  "recipe": {},
  "model": "string"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

POST /api/v1/ai/automation-draft/import

Import a drafted automation. Imports a recipe returned by the draft route as a draft automation, the way a gallery recipe is imported: `choices` names, per placeholder, an existing id (`{ "existing": id }`), a name to create (`{ "create": name }`) or `{ "later": true }`. The recipe is rebuilt from a whitelist before it is trusted. Requires `automations:write`, plus the write permission for anything a choice would create.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/ai/automation-draft/import" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "recipe": {},
  "choices": {},
  "name": "string"
}'

Responses

{
  "automation": {
    "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome series",
    "description": "Three emails over a week",
    "trigger_type": "contact_created",
    "trigger_config": {},
    "status": "active",
    "created_at": "2026-08-26T08:00:00.000Z"
  },
  "created": {},
  "unresolved": [
    "string"
  ]
}

{
  "error": "Contact not found"
}

GET /api/v1/templates

List templates. Returns templates, newest first, optionally filtered by category. Requires `templates:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/templates?category=welcome" \
  -H "x-api-key: sb_live_…"

Responses

{
  "templates": [
    {
      "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "Welcome email",
      "subject": "Welcome, {{first_name}}!",
      "html_content": "<h1>Hi {{first_name}}</h1>",
      "category": "welcome",
      "created_at": "2026-08-20T09:00:00.000Z"
    }
  ]
}

POST /api/v1/templates

Create a template. Creates a template. An unknown or missing `category` becomes `custom`. `html_content` is limited to 500,000 characters (`413`). Send `blocks` — the visual builder's block JSON — alongside `html_content` rendered from it and the template reopens in the visual builder; leave it out or send `null` for an HTML-only template. At most 200 blocks / 200,000 characters of block JSON (`400`). Requires `templates:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/templates" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Welcome email",
  "subject": "Welcome to {{first_name}}!",
  "html_content": "<h1>Hi {{first_name}}</h1><p>Thanks for joining.</p>",
  "category": "welcome",
  "blocks": [
    {
      "id": "block_1",
      "type": "text",
      "props": {
        "heading": "This month",
        "text": "Hi {{first_name|there}},",
        "padding": 24
      }
    }
  ]
}'

Responses

{
  "template": {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome email",
    "subject": "Welcome, {{first_name}}!",
    "html_content": "<h1>Hi {{first_name}}</h1>",
    "category": "welcome",
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

{
  "error": "html_content is required"
}

GET /api/v1/custom-blocks

List custom blocks. The workspace's own email blocks, by name. Requires `templates:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/custom-blocks" \
  -H "x-api-key: sb_live_…"

Responses

{
  "custom_blocks": [
    {
      "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "Hero",
      "description": "Headline, one line and a button on the brand colour.",
      "mjml": "<mjml><mj-body><mj-section background-color=\"#111827\"><mj-column><mj-text color=\"#ffffff\" font-size=\"28px\">[[headline]]</mj-text><mj-button href=\"[[cta:url]]\">[[cta_label]]</mj-button></mj-column></mj-section></mj-body></mjml>",
      "html": "<div style=\"\">…[[headline]]…</div>",
      "head_html": "<style type=\"text/css\">…</style>",
      "slots": [
        {
          "key": "headline",
          "type": "text",
          "label": "Headline",
          "default": "Big news"
        },
        {
          "key": "cta",
          "type": "url",
          "label": "Button link",
          "default": "https://acme.test"
        },
        {
          "key": "cta_label",
          "type": "text",
          "label": "Button text",
          "default": "Read more"
        }
      ],
      "created_at": "2026-09-26T09:00:00.000Z",
      "updated_at": "2026-09-26T09:00:00.000Z"
    }
  ]
}

POST /api/v1/custom-blocks

Create a custom block. Compiles the MJML once and stores the block. Mark what a marketer may change as slots: `[[headline]]` for text, `[[cta:url]]` for a link, `[[hero:image]]` for an image. `slots` may set a label and a default per key; keys and types always come from the markup. `400` names the problem when the MJML does not compile; soft findings (an attribute MJML ignored) come back as `warnings` on a `201`. `mjml` is limited to 100,000 characters (`413`). Requires `templates:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/custom-blocks" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Hero",
  "description": "string",
  "mjml": "string",
  "slots": [
    {
      "key": "string",
      "label": "string",
      "default": "string"
    }
  ]
}'

Responses

{
  "custom_block": {
    "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Hero",
    "description": "Headline, one line and a button on the brand colour.",
    "mjml": "<mjml><mj-body><mj-section background-color=\"#111827\"><mj-column><mj-text color=\"#ffffff\" font-size=\"28px\">[[headline]]</mj-text><mj-button href=\"[[cta:url]]\">[[cta_label]]</mj-button></mj-column></mj-section></mj-body></mjml>",
    "html": "<div style=\"\">…[[headline]]…</div>",
    "head_html": "<style type=\"text/css\">…</style>",
    "slots": [
      {
        "key": "headline",
        "type": "text",
        "label": "Headline",
        "default": "Big news"
      },
      {
        "key": "cta",
        "type": "url",
        "label": "Button link",
        "default": "https://acme.test"
      },
      {
        "key": "cta_label",
        "type": "text",
        "label": "Button text",
        "default": "Read more"
      }
    ],
    "created_at": "2026-09-26T09:00:00.000Z",
    "updated_at": "2026-09-26T09:00:00.000Z"
  },
  "warnings": [
    "string"
  ]
}

{
  "error": "mjml must be a whole document: start with <mjml> and put the block inside <mj-body>."
}

POST /api/v1/custom-blocks/preview

Compile MJML without saving. What the block editor shows while you type: the compiled fragment and head, the slots the markup declares, and `document`, a whole email with the slots filled from `values` (or their defaults) for a preview frame. Nothing is stored. Requires `templates:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/custom-blocks/preview" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "mjml": "string",
  "slots": [
    {
      "key": "string",
      "label": "string",
      "default": "string"
    }
  ],
  "values": {}
}'

Responses

{
  "html": "string",
  "head_html": "string",
  "slots": [
    {
      "key": "headline",
      "type": "text",
      "label": "Headline",
      "default": "Big news"
    }
  ],
  "warnings": [
    "string"
  ],
  "document": "string"
}

{
  "error": "The MJML compiled to an empty body. Put the block inside <mj-body>."
}

GET /api/v1/custom-blocks/{id}

Get a custom block. One block, source and compiled output. Requires `templates:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/custom-blocks/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "custom_block": {
    "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Hero",
    "description": "Headline, one line and a button on the brand colour.",
    "mjml": "<mjml><mj-body><mj-section background-color=\"#111827\"><mj-column><mj-text color=\"#ffffff\" font-size=\"28px\">[[headline]]</mj-text><mj-button href=\"[[cta:url]]\">[[cta_label]]</mj-button></mj-column></mj-section></mj-body></mjml>",
    "html": "<div style=\"\">…[[headline]]…</div>",
    "head_html": "<style type=\"text/css\">…</style>",
    "slots": [
      {
        "key": "headline",
        "type": "text",
        "label": "Headline",
        "default": "Big news"
      },
      {
        "key": "cta",
        "type": "url",
        "label": "Button link",
        "default": "https://acme.test"
      },
      {
        "key": "cta_label",
        "type": "text",
        "label": "Button text",
        "default": "Read more"
      }
    ],
    "created_at": "2026-09-26T09:00:00.000Z",
    "updated_at": "2026-09-26T09:00:00.000Z"
  }
}

PATCH /api/v1/custom-blocks/{id}

Update a custom block. Any of `name`, `description`, `mjml` and `slots`. New MJML is compiled; labels and defaults already set survive a markup change, and a slot the markup no longer names is dropped. Emails that already placed the block keep the copy they took; the builder picks up the new design when they are next opened. Requires `templates:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/custom-blocks/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "mjml": "string",
  "slots": [
    {
      "key": "string",
      "label": "string",
      "default": "string"
    }
  ]
}'

Responses

{
  "custom_block": {
    "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Hero",
    "description": "Headline, one line and a button on the brand colour.",
    "mjml": "<mjml><mj-body><mj-section background-color=\"#111827\"><mj-column><mj-text color=\"#ffffff\" font-size=\"28px\">[[headline]]</mj-text><mj-button href=\"[[cta:url]]\">[[cta_label]]</mj-button></mj-column></mj-section></mj-body></mjml>",
    "html": "<div style=\"\">…[[headline]]…</div>",
    "head_html": "<style type=\"text/css\">…</style>",
    "slots": [
      {
        "key": "headline",
        "type": "text",
        "label": "Headline",
        "default": "Big news"
      },
      {
        "key": "cta",
        "type": "url",
        "label": "Button link",
        "default": "https://acme.test"
      },
      {
        "key": "cta_label",
        "type": "text",
        "label": "Button text",
        "default": "Read more"
      }
    ],
    "created_at": "2026-09-26T09:00:00.000Z",
    "updated_at": "2026-09-26T09:00:00.000Z"
  },
  "warnings": [
    "string"
  ]
}

{
  "error": "Nothing to update"
}

DELETE /api/v1/custom-blocks/{id}

Delete a custom block. Removes the block from the library. Emails that placed it keep their copy. Requires `templates:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/custom-blocks/id" \
  -H "x-api-key: sb_live_…"

Responses

GET /api/v1/templates/{id}

Get a template. Returns one template. Requires `templates:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/templates/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "template": {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome email",
    "subject": "Welcome, {{first_name}}!",
    "html_content": "<h1>Hi {{first_name}}</h1>",
    "category": "welcome",
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

PATCH /api/v1/templates/{id}

Update a template. Updates any of the template fields. Empty `name`/`subject` and invalid `category` values are ignored. `html_content` is limited to 500,000 characters (`413`). `blocks` (the visual builder's block JSON) is stored when sent; sending new `html_content` without `blocks` clears them, so stale block JSON never masquerades as the current design. Requires `templates:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/templates/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Welcome aboard, {{first_name}}"
}'

Responses

{
  "template": {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome email",
    "subject": "Welcome, {{first_name}}!",
    "html_content": "<h1>Hi {{first_name}}</h1>",
    "category": "welcome",
    "created_at": "2026-08-20T09:00:00.000Z"
  }
}

DELETE /api/v1/templates/{id}

Delete a template. Deletes the template. Returns `204` with no body. Requires `templates:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/templates/id" \
  -H "x-api-key: sb_live_…"

Responses

GET /api/v1/media

List hosted images. Every image the workspace has uploaded, newest first, with the storage used and the plan's cap. Always `200`: when image hosting is not enabled on the installation the body says `configured: false` with an empty list, so a client can decide whether to offer an upload at all. Requires `campaigns:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/media" \
  -H "x-api-key: sb_live_…"

Responses

{
  "configured": true,
  "files": [
    {
      "id": "mfp3k2x0a1b2c3d4e5f6.jpg",
      "url": "https://media.sendbeam.io/m/7c9e6679742a4b1d9a3f0e2c/mfp3k2x0a1b2c3d4e5f6.jpg",
      "name": "hero.jpg",
      "size": 184320,
      "type": "image/jpeg",
      "uploaded": "2026-09-14T09:00:00.000Z"
    }
  ],
  "count": 1,
  "used_bytes": 184320,
  "quota_bytes": 26214400,
  "max_bytes": 2097152,
  "types": [
    "image/png",
    "image/jpeg",
    "image/gif",
    "image/webp"
  ],
  "truncated": false
}

{
  "error": "Contact not found"
}

POST /api/v1/media

Upload an image. Hosts one image and returns its public URL for use in an email. Send `multipart/form-data` with the file in a field called `file`. The bytes are inspected: PNG, JPEG, GIF and WebP are accepted by their signature, whatever the declared type or file name; anything else is `415` (SVG included — email clients do not render it and it can carry script). At most 2 MB (`413`). Storage is capped per plan (`403` with `used_bytes` and `quota_bytes` when the file would not fit) and uploads at 120 an hour per workspace (`429`). The URL is permanent for as long as the file exists; a later delete leaves emails that used it with a broken picture. Requires `campaigns:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/media" \
  -H "x-api-key: sb_live_…"

Responses

{
  "file": {
    "id": "mfp3k2x0a1b2c3d4e5f6.jpg",
    "url": "https://media.sendbeam.io/m/7c9e6679742a4b1d9a3f0e2c/mfp3k2x0a1b2c3d4e5f6.jpg",
    "name": "hero.jpg",
    "size": 184320,
    "type": "image/jpeg",
    "uploaded": "2026-09-14T09:00:00.000Z"
  },
  "used_bytes": 184320,
  "quota_bytes": 26214400
}

{
  "error": "Contact not found"
}

{
  "error": "string",
  "used_bytes": 1,
  "quota_bytes": 1
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

{
  "error": "string",
  "configured": true
}

DELETE /api/v1/media/{id}

Remove a hosted image. Deletes the file. Ids are resolved inside the caller's own workspace, so another workspace's id is simply `404`. Emails that already reference the URL keep the reference and show a broken picture. Requires `campaigns:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/media/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "ok": true,
  "id": "string",
  "note": "string"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

GET /api/v1/rss-feeds

List feeds.

Example request

curl -X GET "https://sendbeam.io/api/v1/rss-feeds" \
  -H "x-api-key: sb_live_…"

Responses

{
  "feeds": [
    null
  ]
}

POST /api/v1/rss-feeds

Add a feed. Watches an RSS 2.0 or Atom feed and sends new posts to the audience as a campaign. The feed is fetched and parsed before it is saved: a URL that is not a working feed is refused with `422` and the reason, and a successful create answers with `check` (how many posts the feed holds and the newest title) and stores the feed's title. Checked continuously afterwards: `immediate` feeds every 15 minutes, `daily`/`weekly` feeds hourly with the send in `send_hour` (UTC). Requires `campaigns:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/rss-feeds" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "feed_url": "string",
  "send_to_type": "all",
  "send_to_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "template_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "subject_template": "{{item_title}}",
  "intro": "string",
  "frequency": "daily",
  "send_hour": 9,
  "send_weekday": 1,
  "max_items": 5,
  "status": "active"
}'

Responses

{
  "feed": null,
  "check": {
    "total_items": 12,
    "newest_title": "What shipped in September"
  }
}

{
  "error": "feed_url must be a public hostname"
}

{
  "error": "List not found"
}

{
  "error": "That URL is not an RSS or Atom feed."
}

GET /api/v1/rss-feeds/{id}

Get a feed and its recent campaigns.

Example request

curl -X GET "https://sendbeam.io/api/v1/rss-feeds/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "feed": null,
  "campaigns": [
    {}
  ]
}

{
  "error": "Feed not found"
}

PATCH /api/v1/rss-feeds/{id}

Update a feed. Any subset of the create fields, plus `status` (`active` / `paused`). A new `feed_url` is fetched and parsed before it replaces the old one (`422` with the reason if it is not a working feed); on success the response carries `check` and any earlier `last_error` is cleared. Requires `campaigns:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/rss-feeds/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "feed_url": "string",
  "send_to_type": "all",
  "send_to_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "template_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "subject_template": "{{item_title}}",
  "intro": "string",
  "frequency": "daily",
  "send_hour": 9,
  "send_weekday": 1,
  "max_items": 5,
  "status": "active"
}'

Responses

{
  "feed": null,
  "check": {
    "total_items": 12,
    "newest_title": "What shipped in September"
  }
}

{
  "error": "status must be active or paused"
}

{
  "error": "Feed not found"
}

{
  "error": "The feed answered HTTP 404."
}

DELETE /api/v1/rss-feeds/{id}

Delete a feed. Campaigns already sent from it are kept (their `rss_feed_id` becomes null). Requires `campaigns:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/rss-feeds/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Feed not found"
}

POST /api/v1/rss-feeds/{id}/preview

Fetch the feed and render the email. Fetches the feed now and returns what a send would contain — the new items (or, when nothing is new, the newest ones as a sample), the subject and the rendered HTML. Nothing is sent or recorded. Requires `campaigns:read`.

Example request

curl -X POST "https://sendbeam.io/api/v1/rss-feeds/id/preview" \
  -H "x-api-key: sb_live_…"

Responses

{
  "feed_title": "string",
  "total_items": 1,
  "new_items": 1,
  "items": [
    {
      "key": "string",
      "title": "string",
      "link": "string",
      "summary": "string",
      "date": "2026-09-02T12:00:00Z"
    }
  ],
  "subject": "string",
  "html": "string"
}

{
  "error": "Feed not found"
}

{
  "error": "That URL is not an RSS or Atom feed."
}

POST /api/v1/rss-feeds/{id}/run

Send now. Sends the posts that are new since the last send as a campaign. With `{"force": true}` the newest posts are sent even if nothing is new. "Nothing new" is a `200` with `sent: false`. Requires `campaigns:send` — running a feed sends a campaign, unlike editing the feed itself (`campaigns:write`).

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/rss-feeds/id/run" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "force": false
}'

Responses

{
  "sent": false,
  "reason": "string",
  "items": 1
}

{
  "sent": true,
  "campaign_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "items": 1,
  "subject": "string"
}

{
  "error": "Invalid JSON body"
}

{
  "error": "Feed not found"
}

GET /api/v1/automations

List automations. Returns automations, newest first, without their steps. Optionally filter by status. Requires `automations:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/automations?status=active" \
  -H "x-api-key: sb_live_…"

Responses

{
  "automations": [
    {
      "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "Welcome series",
      "description": "Three emails over a week",
      "trigger_type": "contact_created",
      "trigger_config": {},
      "status": "active",
      "created_at": "2026-08-26T08:00:00.000Z"
    }
  ]
}

POST /api/v1/automations

Create an automation. Creates an automation in `draft` status with its steps. `steps` is required but may be empty. Every template, tag, list or form referenced in `trigger_config` or a step's `config` must belong to this workspace; otherwise `400` names the offending field. Activate it separately. The response contains the automation without its steps. Requires `automations:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/automations" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Welcome series",
  "trigger_type": "contact_created",
  "trigger_config": {},
  "steps": [
    {
      "type": "send_email",
      "config": {
        "template_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
      }
    },
    {
      "type": "wait",
      "config": {
        "duration_minutes": 1440
      }
    },
    {
      "type": "add_tag",
      "config": {
        "tag_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33"
      }
    }
  ]
}'

Responses

{
  "automation": {
    "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome series",
    "description": "Three emails over a week",
    "trigger_type": "contact_created",
    "trigger_config": {},
    "status": "active",
    "created_at": "2026-08-26T08:00:00.000Z"
  }
}

{
  "error": "Contact not found"
}

{
  "error": "Failed to save automation steps"
}

GET /api/v1/automations/{id}

Get an automation. Returns one automation with its steps in order. Requires `automations:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/automations/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "automation": null
}

PATCH /api/v1/automations/{id}

Update an automation. Updates any of `name`, `description`, `trigger_type`, `trigger_config`; if `steps` is present every existing step is replaced by the new array. The whole body is validated before anything is written — including that every referenced template, tag, list or form belongs to this workspace — so a rejected request changes nothing. Contacts already enrolled continue from their current step index. The response contains the automation without its steps. Requires `automations:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/automations/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Welcome series v2"
}'

Responses

{
  "automation": {
    "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome series",
    "description": "Three emails over a week",
    "trigger_type": "contact_created",
    "trigger_config": {},
    "status": "active",
    "created_at": "2026-08-26T08:00:00.000Z"
  }
}

{
  "error": "Contact not found"
}

{
  "error": "Failed to update automation"
}

DELETE /api/v1/automations/{id}

Delete an automation. Deletes the automation together with its steps and every enrolment (active or finished). Requires `automations:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/automations/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Automation not found"
}

POST /api/v1/automations/{id}/activate

Activate an automation. Runs the pre-flight checks and, if they pass, sets the automation to `active` so new trigger events enrol contacts. Refused with `422` and a `blockers` list when it could not do what it says: no steps or trigger, an email step with nothing to send (a template that no longer exists, or no subject/content), a step or trigger pointing at a tag, list, form or automation that no longer exists, a wait with no length, or a workspace that cannot send. Non-blocking `warnings` (no email step, an unreachable step) come back with the `200`. Counts against the plan's live-automation cap, which is per workspace. Requires `automations:write`.

Example request

curl -X POST "https://sendbeam.io/api/v1/automations/id/activate" \
  -H "x-api-key: sb_live_…"

Responses

{
  "automation": {
    "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome series",
    "description": "Three emails over a week",
    "trigger_type": "contact_created",
    "trigger_config": {},
    "status": "active",
    "created_at": "2026-08-26T08:00:00.000Z"
  },
  "warnings": [
    {
      "code": "template_missing",
      "message": "string",
      "step_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    }
  ]
}

{
  "error": "Your plan allows 5 live automations in this workspace. Pause one or upgrade."
}

{
  "error": "Automation is already active"
}

{
  "error": "This automation cannot be activated yet: step 1 sends a template that no longer exists — choose another or write the email in the step.",
  "blockers": [
    {
      "code": "template_missing",
      "step_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "message": "step 1 sends a template that no longer exists — choose another or write the email in the step."
    }
  ],
  "warnings": []
}

{
  "error": "Failed to activate automation"
}

POST /api/v1/automations/{id}/pause

Pause an automation. Sets the automation to `paused`; no new enrolments happen and pending steps stop advancing. Works from `active` or `draft`. Requires `automations:write`.

Example request

curl -X POST "https://sendbeam.io/api/v1/automations/id/pause" \
  -H "x-api-key: sb_live_…"

Responses

{
  "automation": {
    "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Welcome series",
    "description": "Three emails over a week",
    "trigger_type": "contact_created",
    "trigger_config": {},
    "status": "active",
    "created_at": "2026-08-26T08:00:00.000Z"
  }
}

{
  "error": "Automation is already paused"
}

{
  "error": "Failed to pause automation"
}

POST /api/v1/automations/{id}/trigger

Start an automation for one contact. Enrols a single contact, bypassing trigger matching, and runs the first steps straight away in the background of this request (a wait, or anything the request could not finish, is picked up by the scheduler within about a minute). The automation must be `active` and must carry a trigger of type `api` — otherwise nothing on the outside could be allowed to inject contacts into a sequence whose author never meant it to be driven that way. Every other rule still applies: subscribed contacts only, never enrolled twice at once, and repeats obey `repeat_enabled` and `repeat_cooldown_hours`. Requires `automations:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/automations/id/trigger" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "email": "jane@example.com"
}'

Responses

{
  "enrolled": true,
  "automation_id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
  "contact_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "error": "contact_id or email is required"
}

{
  "error": "Contact not found"
}

{
  "enrolled": false,
  "reason": "The contact was not enrolled. The automation needs a trigger of type \"api\", and the contact must be subscribed, not already in this automation, and past its repeat cooldown."
}

{
  "error": "Internal server error"
}

GET /api/v1/automation-recipes

List automation recipes. The gallery behind "New automation": ready-made automations (welcome series, tag hand-off, birthday, renewal reminder, re-engagement, post-purchase, form → sales, signup anniversary), each with its trigger, its steps in order and the placeholders — a list, a tag, a form, a Date field — an import has to resolve. Requires `automations:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/automation-recipes" \
  -H "x-api-key: sb_live_…"

Responses

{
  "recipes": [
    {
      "slug": "welcome-series",
      "name": "Welcome series",
      "tagline": "Three emails over a week for everyone who joins a list.",
      "description": "…",
      "outline": {
        "triggers": [
          "Contact joins list \"List to watch\""
        ],
        "steps": [
          {
            "text": "Send “Welcome — here is what to expect”"
          },
          {
            "text": "Wait 2 days"
          }
        ],
        "repeats": "Each contact goes through once"
      },
      "placeholders": [
        {
          "id": "list",
          "kind": "list",
          "label": "List to watch",
          "hint": "Joining this list starts the series.",
          "suggested": "Newsletter"
        }
      ]
    }
  ]
}

GET /api/v1/automation-recipes/{slug}

Get one recipe. One recipe with its outline and placeholders — what a `POST` here will ask about. Requires `automations:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/automation-recipes/slug" \
  -H "x-api-key: sb_live_…"

Responses

{
  "recipe": {
    "slug": "welcome-series",
    "name": "Welcome series",
    "tagline": "Three emails over a week for everyone who joins a list.",
    "description": "…",
    "outline": {
      "triggers": [
        "Contact joins list \"List to watch\""
      ],
      "steps": [
        {
          "text": "Send “Welcome — here is what to expect”"
        },
        {
          "text": "Wait 2 days"
        }
      ],
      "repeats": "Each contact goes through once"
    },
    "placeholders": [
      {
        "id": "list",
        "kind": "list",
        "label": "List to watch",
        "hint": "Joining this list starts the series.",
        "suggested": "Newsletter"
      }
    ]
  }
}

{
  "error": "Recipe not found"
}

POST /api/v1/automation-recipes/{slug}

Create a draft automation from a recipe. Materialises the recipe into a `draft` automation (never active) with its starter copy, resolving each placeholder by the choice given: `{ existing: <id or key> }` uses something the workspace already has; `{ create: <name or key> }` makes it now — a tag or list of that name is reused case-insensitively, a field is registered with the recipe's type when the custom-field registry exists; `{ later: true }` (tags, lists and forms only) leaves the slot empty with a `recipe_placeholder` marker in the config, so the automation cannot be activated until it is chosen in the editor or the author explicitly opts for "any". A placeholder with no choice takes the recipe's suggestion (create it; a form is left for later), so an empty body is a complete import. A recipe with an anniversary trigger inherits the yearly repeat default. Requires `automations:write`; a choice that creates something also needs that thing's own permission (`tags:write`, `lists:write`, `contacts:write` for a field), or the call is refused with `403` before anything is made.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/automation-recipes/slug" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Newsletter welcome",
  "choices": {
    "list": {
      "existing": "9c1e2d3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"
    },
    "welcomed": {
      "create": "Welcomed"
    }
  }
}'

Responses

{
  "automation": {
    "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "name": "Welcome series",
    "status": "draft",
    "trigger_type": "list_joined"
  },
  "created": {
    "tags": [
      "Welcomed"
    ],
    "lists": [
      "Newsletter"
    ],
    "fields": []
  },
  "unresolved": [],
  "registry_unavailable": false
}

{
  "error": "choices.list: 9c1e… is not a list in this workspace"
}

{
  "error": "Recipe not found"
}

{
  "error": "Contact not found"
}

POST /api/v1/events

Tell SendBeam that something happened. Reports an event by NAME, and runs every active automation carrying the "Something happened elsewhere" trigger for that name. The caller says what happened; the workspace decides what it should do, so neither side has to know the other's automation ids — unlike `POST /api/v1/automations/{id}/trigger`, which names one automation and breaks when it is rebuilt. An event never creates a contact: somebody else's system mentioning an address is not consent to email it. An address the workspace does not hold answers `200` with `"matched": false` rather than an error, so a sender does not retry a normal case for ever. Names are lower-cased, so `Deal_Won` and `deal_won` are one event. Requires `contacts:write`, because running an automation can send email.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/events" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "deal_won",
  "email": "jane@example.com"
}'

Responses

{
  "ok": true,
  "event": "string",
  "matched": true,
  "enrolled": 1
}

{
  "error": "event must be 1-60 characters: letters, numbers, dot, dash or underscore"
}

GET /api/v1/workspace-blueprints

List the account's blueprints. Every blueprint saved on this login's account, newest first, with counts of what each one captured. Requires `automations:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/workspace-blueprints" \
  -H "x-api-key: sb_live_…"

Responses

{
  "blueprints": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "account_id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
      "source_tenant_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
      "created_by": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "name": "Agency starter kit",
      "description": "",
      "created_at": "2026-09-15T09:00:00.000Z",
      "updated_at": "2026-09-15T09:00:00.000Z",
      "counts": {
        "custom_fields": 2,
        "automations": 1,
        "templates": 3
      }
    }
  ],
  "available": true
}

POST /api/v1/workspace-blueprints

Save the current workspace as a blueprint. Captures the AUTHENTICATED workspace's custom-field definitions, its automations (each turned back into the same recipe shape `POST /api/v1/automation-recipes/{slug}` resolves, so applying one goes through that same import) and its email templates (any hosted image a template references is copied into the destination workspace on apply). Contacts, lists and sending domains are never captured. Admin-only; requires `automations:read`, `templates:read` and `contacts:read` (reading every domain a blueprint touches).

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/workspace-blueprints" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Agency starter kit",
  "description": "Custom fields, welcome automation and templates every new client site starts with."
}'

Responses

{
  "blueprint": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "account_id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
    "source_tenant_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
    "created_by": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "name": "Agency starter kit",
    "description": "",
    "created_at": "2026-09-15T09:00:00.000Z",
    "updated_at": "2026-09-15T09:00:00.000Z",
    "counts": {
      "custom_fields": 2,
      "automations": 1,
      "templates": 3
    }
  }
}

{
  "error": "Give the blueprint a name between 2 and 80 characters."
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

DELETE /api/v1/workspace-blueprints/{id}

Delete a blueprint. Removes the blueprint from the account. Never touches a workspace it was already applied to — applying one copies its content in, so nothing keeps pointing back at the blueprint row afterward. Admin-only.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/workspace-blueprints/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Contact not found"
}

{
  "error": "Blueprint not found"
}

{
  "error": "Contact not found"
}

POST /api/v1/workspace-blueprints/{id}/apply

Apply a blueprint into a workspace. Materialises the blueprint into `tenant_id`: custom fields are created (a key already declared there is left alone and reported as skipped, never overwritten), each captured automation is imported as a `draft` exactly as `POST /api/v1/automation-recipes/{slug}` would (a tag/list/field it needs is created under its captured name, reusing one of that name if it already exists there), and each template is created with any hosted image copied into the destination's own storage (a note says how many could not be, rather than shipping a broken image reference). The target workspace must belong to the SAME account as the blueprint. A session caller may target any workspace they hold the admin role in; an API key, as everywhere else in this API, may only target the one workspace it was minted for.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/workspace-blueprints/id/apply" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}'

Responses

{
  "applied": {
    "custom_fields": {
      "created": [
        "renewal_date"
      ],
      "skipped": [
        "plan"
      ],
      "unavailable": false
    },
    "templates": {
      "created": 3,
      "failed": 0,
      "media_copied": 2,
      "media_not_carried_over": 0
    },
    "automations": {
      "created": [
        {
          "name": "Welcome series",
          "id": "f6e5d4c3-b2a1-4f0e-9d8c-7b6a5f4e3d2c",
          "unresolved": []
        }
      ],
      "failed": []
    }
  }
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

{
  "error": "Blueprint not found"
}

{
  "error": "Contact not found"
}

GET /api/v1/forms

List forms. Returns every form in the workspace, newest first, each with its `views`, `submissions` and `conversion_rate` (see the Form schema). `turnstile_secret` is always masked (`••••••••` when set, `null` otherwise). Requires `forms:read` (`forms:write` or a legacy `automations:write` also satisfies it).

Example request

curl -X GET "https://sendbeam.io/api/v1/forms" \
  -H "x-api-key: sb_live_…"

Responses

{
  "forms": [
    {
      "id": "11111111-2222-4333-8444-555555555555",
      "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
      "name": "Newsletter signup",
      "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "fields": [
        "email",
        "first_name",
        "last_name",
        "company"
      ],
      "thank_you_message": "Thanks for subscribing!",
      "redirect_url": null,
      "status": "active",
      "kind": "signup",
      "notify_email": null,
      "notify_subject": null,
      "allowed_origins": [
        "https://acme.com"
      ],
      "turnstile_site_key": "0x4AAAAAAA",
      "turnstile_secret": "••••••••",
      "daily_cap": 200,
      "created_at": "2026-08-28T14:00:00.000Z",
      "views": 1840,
      "submissions": 92,
      "conversion_rate": 0.05
    }
  ]
}

{
  "error": "Failed to fetch forms"
}

POST /api/v1/forms

Create a form. Creates an active form. `kind` is `signup` (default: creates/subscribes a contact, optionally joins `list_id`, which must be one of this workspace's lists) or `contact` (emails the message to `notify_email`, never creates a contact; `list_id` is forced to null). `notify_email` must be a workspace member's address or an address on one of the workspace's verified sending domains (`400` otherwise). Defaults: `fields` `["email","first_name","last_name"]` for signup or `["email","name","subject","message"]` for contact; `thank_you_message` `Thanks for subscribing!` or `Thanks — your message has been sent. We'll reply by email.`. Requires `forms:write` (a legacy `automations:write` is also accepted).

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/forms" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Contact us",
  "kind": "contact",
  "notify_email": "hello@acme.com",
  "notify_subject": "Website enquiry",
  "allowed_origins": [
    "https://acme.com"
  ],
  "daily_cap": 100
}'

Responses

{
  "form": {
    "id": "11111111-2222-4333-8444-555555555555",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Newsletter signup",
    "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "fields": [
      "email",
      "first_name",
      "last_name",
      "company"
    ],
    "thank_you_message": "Thanks for subscribing!",
    "redirect_url": null,
    "status": "active",
    "kind": "signup",
    "notify_email": null,
    "notify_subject": null,
    "allowed_origins": [
      "https://acme.com"
    ],
    "turnstile_site_key": "0x4AAAAAAA",
    "turnstile_secret": "••••••••",
    "daily_cap": 200,
    "created_at": "2026-08-28T14:00:00.000Z",
    "views": 1840,
    "submissions": 92,
    "conversion_rate": 0.05
  }
}

{
  "error": "Failed to create form"
}

PUT /api/v1/forms

Update a form. Updates the form identified by `id` in the body. Only supplied fields change. Sending `turnstile_secret` as the mask `••••••••` leaves the stored secret unchanged. Switching `kind` to `contact` clears `list_id` and requires a `notify_email` (new or already stored). A new `list_id` must be one of this workspace's lists and a new `notify_email` a workspace member's address or one on a verified sending domain (`400` otherwise). Requires `forms:write` (a legacy `automations:write` is also accepted).

Request body

See the OpenAPI document for the body schema.

Example request

curl -X PUT "https://sendbeam.io/api/v1/forms" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "11111111-2222-4333-8444-555555555555",
  "status": "inactive"
}'

Responses

{
  "form": {
    "id": "11111111-2222-4333-8444-555555555555",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Newsletter signup",
    "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "fields": [
      "email",
      "first_name",
      "last_name",
      "company"
    ],
    "thank_you_message": "Thanks for subscribing!",
    "redirect_url": null,
    "status": "active",
    "kind": "signup",
    "notify_email": null,
    "notify_subject": null,
    "allowed_origins": [
      "https://acme.com"
    ],
    "turnstile_site_key": "0x4AAAAAAA",
    "turnstile_secret": "••••••••",
    "daily_cap": 200,
    "created_at": "2026-08-28T14:00:00.000Z",
    "views": 1840,
    "submissions": 92,
    "conversion_rate": 0.05
  }
}

{
  "error": "Failed to update form"
}

DELETE /api/v1/forms

Delete a form. Deletes the form identified by `id` in the body. Requires `forms:write` (a legacy `automations:write` is also accepted).

Request body

Example request

curl -X DELETE "https://sendbeam.io/api/v1/forms" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}'

Responses

{
  "error": "id is required"
}

{
  "error": "Failed to delete form"
}

GET /api/v1/forms/{id}

Get a form. One form by id, with its `views`, `submissions` and `conversion_rate`. `turnstile_secret` is masked as on the list. A form belonging to another workspace is a `404`, never its row. Requires `forms:read` (`forms:write` or a legacy `automations:write` also satisfies it).

Example request

curl -X GET "https://sendbeam.io/api/v1/forms/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "form": {
    "id": "11111111-2222-4333-8444-555555555555",
    "tenant_id": "7a1e9d4c-3b2f-4e8a-9c6d-1f2e3d4c5b6a",
    "name": "Newsletter signup",
    "list_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "fields": [
      "email",
      "first_name",
      "last_name",
      "company"
    ],
    "thank_you_message": "Thanks for subscribing!",
    "redirect_url": null,
    "status": "active",
    "kind": "signup",
    "notify_email": null,
    "notify_subject": null,
    "allowed_origins": [
      "https://acme.com"
    ],
    "turnstile_site_key": "0x4AAAAAAA",
    "turnstile_secret": "••••••••",
    "daily_cap": 200,
    "created_at": "2026-08-28T14:00:00.000Z",
    "views": 1840,
    "submissions": 92,
    "conversion_rate": 0.05
  }
}

POST /api/forms/{formId}

Submit a form (public). Public, no API key: call it from your website with `fetch` or a plain form handler. CORS is open (`Access-Control-Allow-Origin: *`, or the matched origin when the form restricts `allowed_origins`). **Signup forms** upsert a subscribed contact (`source: "form"`), merge any declared custom fields into `custom_fields`, add the contact to the form's list, send a double opt-in email when the list (or the Free plan) requires it — confirmations to one address are throttled, and each counts towards the monthly email allowance — enrol `form_submitted` and `contact_created` automations (and `list_joined` immediately, or on confirmation for double opt-in), and email the owner if `notify_email` is set. A brand-new contact counts against the plan's contact cap. This is also the only way an address on the suppression list can come back. **Contact forms** (`kind: "contact"`) require `message`, store the submission and email it to `notify_email` with the visitor as Reply-To. No contact is created. **Abuse protection.** Submissions are checked against the form being active, its `allowed_origins`, the email address itself, Cloudflare Turnstile when the form has a secret, and rate limits. Automated submissions are also filtered by checks we do not document, and a `200` confirms only that the request was accepted, not that a contact was created — build your integration on the form working for a real person, not on the status code.

Request body

Example request

curl -X POST "https://sendbeam.io/api/forms/formId" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "name": "Jane Doe",
  "subject": "Question about pricing",
  "message": "Do you offer annual billing?",
  "turnstile_token": "string"
}'

Responses

{
  "success": true,
  "message": "Thanks for subscribing!",
  "redirect_url": null
}

{
  "error": "A valid email address is required"
}

{
  "error": "string",
  "turnstile": "string"
}

{
  "error": "Form not found or inactive"
}

{
  "error": "Contact not found"
}

{
  "error": "Failed to subscribe"
}

{
  "error": "Contact not found"
}

POST /api/forms/{formId}/view

Record a form view (public). Public, no API key, no body: the inline embed code sends this once as it loads (`navigator.sendBeacon`), so the form's `views` and `conversion_rate` include the sites it is pasted into. The hosted page and the pop-up count their own views, so nothing needs to call this for them. If you render a form yourself from its endpoint, call it once each time the form is shown to a person. A view is dropped, with the same `204`, when the request looks automated (a crawler user agent, a prefetch or link preview, or more views of one form from one address in an hour than a person would produce). A form that restricts `allowed_origins` takes views only from those origins.

Example request

curl -X POST "https://sendbeam.io/api/forms/formId/view"

Responses

POST /api/v1/send

Send a single email to a contact. Sends one transactional email to a contact from the workspace's sender identity (re-validated on every send: the workspace's own shared address or a domain it has verified). Only `subscribed` contacts can be mailed. Counts against the plan's monthly email quota and its hourly sending ceiling; a paused workspace or exhausted monthly quota is refused with `403`, an exhausted hourly ceiling with `429` and a `Retry-After` header, before anything is sent. Every send is recorded in the workspace's Activity page (filter **API**) with its delivery, open and click events, and is included in Reports. Requires `campaigns:send`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/send" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "subject": "Your receipt",
  "html_content": "<p>Hi {{first_name}}, thanks for your order.</p>",
  "text_content": "Hi Jane, thanks for your order."
}'

Responses

{
  "ok": true
}

{
  "error": "contact_id, subject, and html_content are required"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact not found"
}

{
  "error": "Hourly send limit reached. Try again later."
}

{
  "error": "Failed to send email"
}

POST /api/v1/transactional

Send site email to any address. Sends the email a site sends to its own users — order confirmations, password resets, booking reminders — through the workspace's verified domain. Unlike `POST /api/v1/send`, recipients need not be contacts, and an unsubscribed person still receives mail they asked for (a marketing opt-out does not cover receipts); addresses that bounced or complained before are refused and listed in `skipped`. The message is delivered as written: no merge tags, no tracking, no unsubscribe link. `to`, `cc` and `bcc` each accept an address, `"Name <address>"`, `{ email, name }` or an array of those — every address gets its own copy — up to 10 per call. `from_email` must be on a verified domain (otherwise the workspace sender is used); `from_name` is used either way. `headers` may carry up to ten `X-*` headers. Counts against the monthly quota and hourly ceiling like every send; a bounce or complaint on a non-contact address suppresses that address. When the recipient is a contact, the send shows on their activity page. Requires `transactional:send`. The WordPress plugin's site-email option uses this endpoint.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/transactional" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "Jane Doe <jane@example.com>",
  "cc": "string",
  "bcc": "string",
  "subject": "Your order #1001",
  "html": "<p>Thanks for your order.</p>",
  "text": "Thanks for your order.",
  "reply_to": "orders@example.com",
  "from_name": "Example Shop",
  "from_email": "orders@example.com",
  "headers": {
    "X-Order-Id": "1001"
  }
}'

Responses

{
  "ok": true,
  "sent": [
    {
      "to": "jane@example.com",
      "message_id": "msg_5f8b2c…"
    }
  ]
}

{
  "error": "`to` is required: an email address, \"Name <address>\", { email, name } or an array of those"
}

{
  "error": "Forbidden: transactional:send permission required"
}

{
  "error": "No deliverable recipient: every address is suppressed or not a routable mailbox.",
  "skipped": [
    {
      "to": "old@acme.co",
      "reason": "This address bounced before and is not mailed again."
    },
    {
      "to": "jane@example.com",
      "reason": "Not a deliverable address: example domain — reserved for documentation, never a real mailbox."
    }
  ]
}

{
  "error": "Hourly send limit reached. Try again later."
}

{
  "error": "Sender not allowed."
}

GET /api/v1/webhooks

List webhook endpoints. Returns every webhook endpoint in the workspace, newest first. The signing `secret` is never included — it is shown once when the endpoint is created and can only be replaced, not read back. Requires `webhooks:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/webhooks" \
  -H "x-api-key: sb_live_…"

Responses

{
  "webhooks": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "url": "https://example.com/hooks/sendbeam",
      "description": "Sync new contacts into the CRM",
      "event_types": [
        "contact.created"
      ],
      "filters": {
        "list_ids": [
          "b3f1c2a4-1111-4a2b-8c3d-0000000000aa"
        ]
      },
      "enabled": true,
      "disabled_reason": null,
      "consecutive_failures": 0,
      "last_success_at": null,
      "last_failure_at": null,
      "created_at": "2026-09-02T12:00:00Z"
    }
  ]
}

{
  "error": "Failed to list webhooks"
}

POST /api/v1/webhooks

Create a webhook endpoint. Registers an endpoint and subscribes it to one or more events. The `url` must be `https://`, carry no credentials, and resolve to a public address — a private, loopback or link-local target is refused. Counts against the plan's webhook cap, pooled across all workspaces on the account (Free 1, Starter 5, Pro and Business unlimited). **This is the only response that ever contains `secret`**: store it when you receive it, because no later request can show it again. Requires `webhooks:write`.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/webhooks" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/sendbeam",
  "description": "Sync new contacts into the CRM",
  "event_types": [
    "contact.created",
    "contact.unsubscribed"
  ],
  "filters": {
    "list_ids": [
      "b3f1c2a4-1111-4a2b-8c3d-0000000000aa"
    ]
  }
}'

Responses

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "url": "https://example.com/hooks/sendbeam",
  "description": "Sync new contacts into the CRM",
  "event_types": [
    "contact.created"
  ],
  "filters": {
    "list_ids": [
      "b3f1c2a4-1111-4a2b-8c3d-0000000000aa"
    ]
  },
  "enabled": true,
  "secret": "9f2c1a0b3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8",
  "created_at": "2026-09-02T12:00:00Z"
}

{
  "error": "Contact not found"
}

{
  "error": "Your plan allows 1 webhook endpoint across your workspaces. Delete one or upgrade."
}

{
  "error": "Failed to create webhook"
}

GET /api/v1/webhooks/{id}

Get a webhook endpoint. Returns one endpoint, with the same fields as the list and never the `secret`. Requires `webhooks:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/webhooks/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "webhook": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "url": "https://example.com/hooks/sendbeam",
    "description": "Sync new contacts into the CRM",
    "event_types": [
      "contact.created"
    ],
    "filters": {
      "list_ids": [
        "b3f1c2a4-1111-4a2b-8c3d-0000000000aa"
      ]
    },
    "enabled": true,
    "disabled_reason": null,
    "consecutive_failures": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-09-02T12:00:00Z"
  }
}

PATCH /api/v1/webhooks/{id}

Update a webhook endpoint. Updates any of `url`, `description`, `event_types` and `enabled`; omitted fields are left alone. A changed `url` is re-validated the same way creation validates it. Setting `enabled` to `true` on an endpoint that was auto-disabled clears `disabled_reason` and resets `consecutive_failures` to 0, so it starts again with a clean record. The response never contains `secret`. Requires `webhooks:write`.

Request body

Example request

curl -X PATCH "https://sendbeam.io/api/v1/webhooks/id" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/sendbeam-v2",
  "description": null,
  "event_types": [
    "contact.created"
  ],
  "filters": {
    "list_ids": [
      "b3f1c2a4-1111-4a2b-8c3d-0000000000aa"
    ]
  },
  "enabled": true
}'

Responses

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "url": "https://example.com/hooks/sendbeam",
  "description": "Sync new contacts into the CRM",
  "event_types": [
    "contact.created"
  ],
  "filters": {
    "list_ids": [
      "b3f1c2a4-1111-4a2b-8c3d-0000000000aa"
    ]
  },
  "enabled": true,
  "disabled_reason": null,
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-09-02T12:00:00Z"
}

{
  "error": "No valid fields to update"
}

{
  "error": "Failed to update webhook"
}

DELETE /api/v1/webhooks/{id}

Delete a webhook endpoint. Deletes the endpoint along with its queued and logged deliveries. Requires `webhooks:write`.

Example request

curl -X DELETE "https://sendbeam.io/api/v1/webhooks/id" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "Failed to delete webhook"
}

POST /api/v1/webhooks/{id}/rotate-secret

Rotate the signing secret. Replaces the endpoint's signing secret and returns the new one. The old secret stops verifying immediately — there is no overlap window — so update your receiver as soon as you have the new value. Together with creation, this is the only response that contains `secret`. Requires `webhooks:write`.

Example request

curl -X POST "https://sendbeam.io/api/v1/webhooks/id/rotate-secret" \
  -H "x-api-key: sb_live_…"

Responses

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "secret": "3b7d4bad9bdd2b0d7b3dcb6d9f2c1a0b3d4e5f60718293a4b5c6d7e8f90a1b2c3"
}

{
  "error": "Failed to rotate the signing secret"
}

GET /api/v1/webhooks/{id}/deliveries

List recent deliveries. The delivery log for one endpoint, most recent first, for debugging an integration. The stored request body is omitted by default because it can contain contact data; pass `include=payload` to get it. Requires `webhooks:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/webhooks/id/deliveries?page=1&limit=50" \
  -H "x-api-key: sb_live_…"

Responses

{
  "deliveries": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "event_type": "contact.created",
      "status": "pending",
      "attempts": 1,
      "last_status_code": 200,
      "last_error": null,
      "delivered_at": null,
      "created_at": "2026-09-02T12:00:00Z",
      "payload": {}
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "total_pages": 25
  }
}

{
  "error": "Failed to list deliveries"
}

GET /api/v1/events

List recent events. The most recent events of one type in the workspace, newest first, each exactly the JSON body a webhook endpoint received for it — so an integration can show real data, for example in a test step, before its own endpoint has been sent anything. Events are read from the deliveries made to your webhook endpoints: an event that no endpoint was subscribed to when it happened is not listed, an event sent to several endpoints is listed once, and test events are never listed. `id` is one of that event's delivery ids and stays the same from one call to the next. No events is an empty list, not an error. Requires `webhooks:read`.

Example request

curl -X GET "https://sendbeam.io/api/v1/events?type=contact.created&limit=10" \
  -H "x-api-key: sb_live_…"

Responses

{
  "events": [
    {
      "id": "8d7f3c1e-2b4a-4c6d-9e8f-0a1b2c3d4e5f",
      "event": "contact.created",
      "created_at": "2026-09-11T09:12:04.000Z",
      "data": {
        "contact": {
          "id": "3f0e2b6e-9a11-4d7a-8c3c-2f2b4b1c9d10",
          "email": "ada@example.com",
          "status": "subscribed",
          "first_name": "Ada",
          "last_name": "Lovelace",
          "source": "api",
          "language": null,
          "custom_fields": {},
          "created_at": "2026-09-11T09:12:04.000Z",
          "subscribed_at": "2026-09-11T09:12:04.000Z",
          "unsubscribed_at": null
        }
      }
    }
  ]
}

{
  "error": "Unknown event type: contact.signup. Valid events are: contact.created, contact.updated, …"
}

{
  "error": "Failed to list events"
}

POST /api/v1/webhooks/{id}/test

Send a test event. POSTs one synthetic, signed payload to the endpoint immediately and reports the outcome, so you can check a new endpoint without waiting for a real event. The body has the same shape as a real event of that type — a contact event has the person under `data.contact` — with `"test": true` at the top of `data`, obviously fake values, and a delivery id that starts `test_`, so anything you map from a test keeps working when real events arrive. It defaults to a `contact.created` event; pass `event` to use another. A test is not a real event, so it is not added to the delivery log. The response is `200` whether the endpoint accepted the payload or not — read `ok`. Requires `webhooks:write`.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/webhooks/id/test" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "event": null
}'

Responses

{
  "ok": true,
  "status": 200,
  "error": "timed out"
}

{
  "error": "Unknown event type: contact.exploded"
}

POST /api/v1/connect/exchange

Exchange a connect grant for an API key. Second half of the Connect flow the WordPress plugin uses. The site owner approves the connection at `https://sendbeam.io/connect/wordpress?…` in a pop-up; SendBeam mints an API key with the approved scopes and redirects the pop-up back to `return_to` with `state` and `grant`. The site's SERVER then posts the grant here and receives the key — once. Send no `x-api-key`: the grant is the credential. It is bound to the `state` the site generated and to the site origin the key was minted for, expires ten minutes after it was issued, and is destroyed the first time it is used, so the key never travels through a browser. Scopes are the plugin's own words — `forms`, `contacts:write`, `transactional:send`, `ecommerce`, `domain` — and the key they map to carries the ordinary API permissions behind them. Approving the connection also SETS THE SITE UP, and the response says what was done: the sending domain the owner chose is added with its DNS records (scope `domain`), a workspace with no signup form is given a `Subscribers` list and a `Newsletter signup` form, and a workspace with no from line takes the site's name and `hello@` that domain. Nothing already chosen is changed, and a previous key for the same site — matched by name OR by the host it was minted for — is revoked, so a reconnection replaces rather than accumulates. When there is no domain, `domain_state` and `domain_note` say why: a hosting company's host cannot be added at all, and a plan at its domain cap says so in words.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/connect/exchange" \
  -H "Content-Type: application/json" \
  -d '{
  "grant": "k7Qb2m9x1s4d6f8g0h2j4k6l8n0p2r4t6v8x0z2b4d6",
  "state": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "site_url": "https://example.com"
}'

Responses

{
  "api_key": "sb_live_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
  "key_prefix": "XXXXXXXX",
  "workspace": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "name": "Example Shop"
  },
  "scopes": [
    "forms",
    "transactional:send",
    "domain"
  ],
  "default_form": {
    "id": "8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
    "name": "Newsletter signup"
  },
  "domain": {
    "name": "example.com",
    "verified": false,
    "records": [
      {
        "type": "CNAME",
        "name": "send.example.com",
        "value": "send.9f2c.dom.sendbeam.io",
        "found": null
      }
    ],
    "domain_connect_url": null,
    "checked_at": null
  },
  "domain_state": "ok",
  "domain_note": null,
  "sender": {
    "from_name": "Example Shop",
    "from_email": "hello@example.com"
  }
}

{
  "error": "invalid"
}

{
  "error": "grant_expired_or_used"
}

{
  "error": "rate_limited"
}

GET /api/v1/connect/status

What the connected site still has to do. What the connected site shows its owner: the workspace, the signup form to offer, the sending domain with the DNS records still outstanding, and the sender line. Cheap enough to call on every admin-page render — cache it for a minute — and it makes no external lookups at all once the domain is verified. The `domain` block requires `domains:read` and is `null` without it; it is also `null` for a key that was not minted by a Connect flow, because such a key belongs to no site. `domain_state` and `domain_note` say which of those it is, so a site can tell an owner what to do rather than only that something is missing. Which domain a key is told about is fixed at connection time and cannot be chosen by the caller. The POST form of this call does not count against the workspace’s hourly write allowance: it reads.

Example request

curl -X GET "https://sendbeam.io/api/v1/connect/status" \
  -H "x-api-key: sb_live_…"

Responses

{
  "workspace": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "name": "Example Shop"
  },
  "default_form": {
    "id": "8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
    "name": "Newsletter signup"
  },
  "domain": {
    "name": "example.com",
    "verified": true,
    "records": [
      {
        "type": "CNAME",
        "name": "send.example.com",
        "value": "send.9f2c.dom.sendbeam.io",
        "found": true
      }
    ],
    "domain_connect_url": null,
    "checked_at": "2026-09-23T15:04:05Z"
  },
  "domain_state": "ok",
  "domain_note": null,
  "sender": {
    "from_name": "Example Shop",
    "from_email": "hello@example.com"
  }
}

POST /api/v1/connect/status

Check the sending domain now. The same body, after running the sending domain’s DNS check now — what the Check button under Settings → Sending does. Use it when the owner says they have added the records, rather than waiting for the background re-check. Requires `domains:read`. Rate limited to 12 an hour per key; send `{}` or omit the body for a plain read, which is not limited.

Request body (optional)

Example request

curl -X POST "https://sendbeam.io/api/v1/connect/status" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "check_domain": false
}'

Responses

{
  "workspace": {
    "id": "0f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "name": "Example Shop"
  },
  "default_form": {
    "id": "8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
    "name": "Newsletter signup"
  },
  "domain": {
    "name": "example.com",
    "verified": true,
    "records": [
      {
        "type": "CNAME",
        "name": "send.example.com",
        "value": "send.9f2c.dom.sendbeam.io",
        "found": true
      }
    ],
    "domain_connect_url": null,
    "checked_at": "2026-09-23T15:04:05Z"
  },
  "domain_state": "ok",
  "domain_note": null,
  "sender": {
    "from_name": "Example Shop",
    "from_email": "hello@example.com"
  }
}

{
  "error": "Forbidden: domains:read permission required"
}

{
  "error": "rate_limited",
  "retry_after": 3600,
  "message": "SendBeam re-checks this domain on its own every few minutes. You can ask again in 60 minutes."
}

GET /api/v1/domains/{id}/connect

Send the owner to their registrar to add the records. Automatic DNS (Domain Connect): redirects the SIGNED-IN workspace admin to their own DNS provider, where they approve SendBeam’s records and are sent back. A browser redirect, not an API-key call — it is the address `domain_connect_url` carries in a Connect status body, and it is opened in a tab rather than fetched. When the provider cannot apply the records the browser comes back to SendBeam’s sending settings with a reason instead.

Example request

curl -X GET "https://sendbeam.io/api/v1/domains/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/connect?return_to=string"

Responses

POST /api/v1/connect/disconnect

Revoke the calling key. Revokes THE KEY THAT MADE THIS CALL, and nothing else — there is no key id to send, because the credential is the request. Use it when the site owner disconnects in WordPress, so deleting a plugin does not leave a live key behind that can write contacts and send the site’s mail. The workspace is untouched: the sending domain, the list, the form and the sender stay exactly where they are, and other sites sending from the same domain are unaffected. Any later call with the same key is `401`, which is what makes it idempotent. Like the status check, it does not count against the workspace’s hourly write allowance.

Example request

curl -X POST "https://sendbeam.io/api/v1/connect/disconnect" \
  -H "x-api-key: sb_live_…"

Responses

{
  "error": "This endpoint retires the API key that called it. Sign the request with that key."
}

GET /api/v1/account/audit-log

List audit events. Who did what in the workspace, newest first: sign-ins and sign-outs, two-factor and passkey changes, API keys created and revoked, team changes, sender and domain changes, webhooks, connections, exports, and the account security policy. Cursor-paged: pass the `next_cursor` a page returns as `cursor` for the next one; `next_cursor` is null on the last page. Entries are kept for `retention_days` (365) and a query never reaches further back. Requires `audit:read`; a session caller needs the workspace admin role. `scope=account` (sessions only, for a person who administers every workspace on the account) returns every workspace's events with `workspace_id` and `workspace_name` on each.

Example request

curl -X GET "https://sendbeam.io/api/v1/account/audit-log?cursor=string&limit=50" \
  -H "x-api-key: sb_live_…"

Responses

{
  "events": [
    {
      "id": "0192b6a4-6d3e-7c1a-9f2e-3b4c5d6e7f80",
      "created_at": "2026-09-25T09:12:41.000Z",
      "action": "api_key.created",
      "actor_type": "user",
      "actor_id": "4f8c6d2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "actor_label": "jane@example.com",
      "target_type": "api_key",
      "target_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "target_label": "Zapier",
      "workspace_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
      "workspace_name": "Harbour Lane",
      "metadata": {
        "permissions": [
          "contacts:read",
          "contacts:write"
        ]
      },
      "ip": "203.0.113.7"
    }
  ],
  "next_cursor": null,
  "retention_days": 365
}

{
  "error": "Forbidden: audit:read permission required"
}

{
  "error": "No account"
}

{
  "error": "The audit log could not be read"
}

GET /c/{id}

Web version of a sent campaign. The "view in browser" page for a campaign that has been sent (`{{web_version_url}}` in the email). With `contact` and the signed `token` from that recipient's email the page is personalised — merge tags filled in and a working unsubscribe link; without them, or with a token that does not verify, it renders the campaign with empty merge fields. Drafts, scheduled and cancelled campaigns are 404. Not indexed.

Example request

curl -X GET "https://sendbeam.io/c/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d?contact=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d&token=string"

Responses

GET /p/{poll}/{option}

Where a poll answer lands. The page a poll button in an email opens. The answer is recorded by the click itself — every link in a sent email is tracked per recipient, and this URL on the click event is the answer — so the page stores nothing and only thanks the reader. `poll` is the poll block's id and `option` the button's 1-based position; anything else is 404. Not indexed. Results are in `GET /api/v1/campaigns/{id}/report` under `polls`.

Example request

curl -X GET "https://sendbeam.io/p/string/1"

Responses

GET /api/unsubscribe

Unsubscribe confirmation page. Never changes state (link scanners follow GET). The signed `token` from the email link is required and is verified against `contact` and `campaign`; a link without a valid signature shows an "invalid link" page. A contact on one or more lists sees a preference page — each list ticked, the campaign's own list marked "this email" — with Save preferences (leave only the unticked lists) and Unsubscribe from everything. When another workspace on the same account has marked a list offerable, that page also carries a "More from us" tab — never the one it opens on — listing those lists unticked, with a Sign me up button. Otherwise shows a page with a button that POSTs back with the same parameters. Returns `text/html`.

Example request

curl -X GET "https://sendbeam.io/api/unsubscribe?contact=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d&campaign=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Responses

POST /api/unsubscribe

Unsubscribe a contact. Performs the unsubscribe. Accepts the parameters from the query string (RFC 8058 one-click, as mailbox providers POST to the `List-Unsubscribe` URL) or from a form-encoded body (the confirmation page). The signed `token` is required and must verify against `contact` and `campaign`; links without a valid signature (including those from emails sent before links were signed) are refused with `403`. Sets the contact to `unsubscribed`, adds the address to the workspace's suppression list and, if `campaign` is given, increments that campaign's unsubscribe count. With `action=join` — the "More from us" form on the preference page — nothing is unsubscribed: each id in `join` is a list that another workspace on the same account has marked offerable, and the contact is signed up to it through that workspace's ordinary signup path, so its suppression list, contact cap and double opt-in all apply; the page says only whether anything changed. Returns `text/html`.

Request body (optional)

See the OpenAPI document for the body schema.

Example request

curl -X POST "https://sendbeam.io/api/unsubscribe?contact=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d&campaign=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Responses

GET /api/confirm-optin

Confirm a double opt-in subscription. Target of the link in the double opt-in email. Marks the list membership confirmed and enrols `list_joined` automations. Returns `text/html`.

Example request

curl -X GET "https://sendbeam.io/api/confirm-optin?token=string&list=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Responses

POST /api/v1/mcp

MCP server (Streamable HTTP). A Model Context Protocol server over Streamable HTTP, stateless, JSON responses. Send JSON-RPC 2.0 messages (`initialize`, `ping`, `tools/list`, `tools/call`; a notification alone answers `202`). Authenticate with the workspace API key as `Authorization: Bearer sb_live_…` or in `x-api-key` — or, for an app connected through OAuth (Claude.ai and other clients that sign in rather than take a key), with the access token that sign-in produced; a `401` carries `WWW-Authenticate` naming the protected-resource metadata at `/.well-known/oauth-protected-resource/api/v1/mcp`. Either way the key's permissions decide which tools are listed and callable — each tool is one operation in this document, run with the same checks a direct call gets, and a write spends the same hourly allowance. Behind a feature flag (`404` when off). `GET` and `DELETE` answer `405`: there is no server stream and no session.

Request body

See the OpenAPI document for the body schema.

Example request

curl -X POST "https://sendbeam.io/api/v1/mcp" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": "string",
  "method": "initialize",
  "params": {}
}'

Responses

{}

{}

{
  "error": "Contact not found"
}

POST /api/v1/ecommerce/events

Report a cart, product-view, order, refund or cancellation event. Feeds the three native e-commerce automation triggers (`cart_abandoned`, `product_viewed`, `order_placed` — see `TriggerType`): matches or creates the contact by email using the same rules as every other place a contact is upserted from an external event (a suppressed address is never (re)subscribed; the plan's contact cap is respected), then fires any automation built on the matching trigger — at once, the same as a form submission. `order_placed` also increases the contact's `lifetime_value` custom field (Number, auto-registered) by `value`; it is always ADDED, never overwritten, so orders accumulate. Two auth paths: an `x-api-key` with `ecommerce:write` and this JSON body (the WordPress plugin, n8n, Zapier, your own code); or, alongside it, Shopify's own webhook format verified by `X-Shopify-Hmac-Sha256` against a per-workspace secret set at Settings → E-commerce — post that path directly from Shopify Admin → Settings → Notifications → Webhooks, no app required (`?tenant=<workspace id>` identifies the workspace, since Shopify cannot send a custom header). A Shopify request with no configured secret, or a signature that does not verify, is refused; a request that verifies but names an unmapped topic, or a Shopify checkout/order with no known email yet, is acknowledged (`200`, `processed: false`) rather than treated as an error, since a store's webhook delivery must not be retried forever over something that will never resolve.

Request body

Example request

curl -X POST "https://sendbeam.io/api/v1/ecommerce/events" \
  -H "x-api-key: sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "cart_abandoned",
  "email": "jane@example.com",
  "name": "string",
  "value": 1,
  "currency": "GBP",
  "external_id": "string",
  "order_id": "string",
  "placed_at": "2026-09-02T12:00:00Z",
  "source": "string"
}'

Responses

{
  "ok": true,
  "processed": true,
  "contact_id": "5b1c1f2e-8d3a-4c0b-9e7f-2a6d4c8b1e33",
  "contact_created": false,
  "enrolled": true,
  "lifetime_value": 214.3
}

{
  "error": "Contact not found"
}

{
  "error": "Invalid Shopify webhook signature"
}

{
  "error": "Forbidden: ecommerce:write permission required"
}

{
  "error": "Contact not found"
}