Connect Claude, send events, track your website

• GET /templates List email templates, newest first.
• POST /templates Create an email template. Needs an Idempotency-Key.
• GET /templates/{id} Get one template with its content and version.
• PATCH /templates/{id} Change a template. Needs If-Match.
• GET /workspace The workspace at a glance: setup, work in progress, and what can be done.
• GET /search Find campaigns, templates, segments, lists, audiences, forms, flows and senders by name.
• GET /objects/{id} Open anything by id, or resume a ws_ work session.
• DELETE /objects/{id} Delete a draft campaign or an unused template.
• GET /reference Merge tags, contact fields, brand variables, block types, integrations, flow steps and events.
• POST /test-sends Send a test of a template or campaign to a workspace member.
• POST /sessions/email Start an email: blank, a starter, a copy, or an existing template. Needs an Idempotency-Key.
• POST /templates/{id}/edits Edit an email with block operations, all or nothing. Needs If-Match.
• GET /templates/{id}/preview Render an email as it will send, with its issues.
• GET /assets Find images in the media library and stock photos.
• POST /assets Import an image from a URL into the media library. Needs an Idempotency-Key.
• POST /sessions/campaign Start or open an email campaign draft. Needs an Idempotency-Key.
• PATCH /campaigns/{id} Change an email campaign draft. Needs If-Match.
• GET /campaigns/{id}/check Dry-run a campaign send: recipients, skips, content, plan usage, approval.
• POST /campaigns/{id}/send Send or schedule a campaign with an approval. Needs the send scope and an Idempotency-Key.
• POST /sessions/flow Start a flow, empty or from a recipe, or open an existing one. Needs an Idempotency-Key.
• PATCH /flows/{id} Change a flow’s trigger, steps and goal, or pause it. Needs If-Match.
• GET /flows/{id}/check Dry-run a flow: walk a contact or a sample through it, and list what stops it going live.
• POST /flows/{id}/activate Turn a flow on with an approval. Needs the send scope and an Idempotency-Key.
• POST /approvals Ask a person to approve a campaign send or turning a flow on. Returns the approval link.
• GET /contacts Find contacts by name, address, status, list, segment, tag or conditions. Masked without read:pii.
• POST /contacts Create or update up to 500 contacts, with their lists and tags. Never subscribes anyone.
• GET /contacts/{id} One contact in full: fields, lists, tags, email and SMS consent, events, flows. Needs read:pii.
• POST /imports Import a CSV file of contacts as a job; poll it at /objects/{id}. Needs an Idempotency-Key.
• POST /lists Make a list, rename it, add or remove members. If-Match to change one; an Idempotency-Key to make one.
• GET /audience/preview Count and sample an audience exactly as a send would count it. Saves nothing.
• POST /segments Create or update a segment from a condition tree. If-Match to change one; an Idempotency-Key to make one.
• POST /contact-fields Define a custom contact field: key, label, type and choices. Needs an Idempotency-Key.
• POST /sessions/form Start or open a signup form draft. Needs an Idempotency-Key.
• PATCH /forms/{id} Change a signup form. Needs If-Match; a live form also needs the publish scope.
• GET /forms/{id}/check Check a signup form before it goes live: blockers, advisories, preview link.
• POST /forms/{id}/publish Put a signup form live and get its embed code, or take it down. Needs the publish scope and If-Match.
• GET /analytics Results for a campaign, flow, form, segment or list, or the workspace by metric over a time range.
• GET /webhooks List webhook endpoints and how their deliveries are going. Never includes a secret.
• POST /webhooks Add a webhook endpoint (its secret is returned once), or change one with If-Match. Needs an Idempotency-Key and the webhooks scope.
• GET /webhooks/{id} Get one webhook endpoint with its version.
• DELETE /webhooks/{id} Remove a webhook endpoint and its delivery log.
• POST /webhooks/{id}/test Send a signed webhook.test event now and see how the endpoint answered.
• GET /webhooks/{id}/deliveries The delivery log of one endpoint: status, attempts and the last error, for 30 days.
• POST /webhooks/{id}/deliveries/{delivery_id}/retry Send a failed delivery again, with the same event id.

curl -X POST https://envoi.email/api/v1/templates \
  -H "Authorization: Bearer env_PASTE_YOUR_KEY_HERE" \
  -H "Idempotency-Key: welcome-email-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Welcome","subject":"Welcome to Acme","blocks":[{"type":"text","props":{"content":"<p>Hi {{first_name}}</p>"}}]}'

curl -X PATCH https://envoi.email/api/v1/templates/TEMPLATE_ID \
  -H "Authorization: Bearer env_PASTE_YOUR_KEY_HERE" \
  -H 'If-Match: "VERSION_FROM_THE_ETAG"' \
  -H "Content-Type: application/json" \
  -d '{"subject":"Welcome aboard"}'

Create keys in Settings, API keys. A key belongs to the workspace, not to the person who made it, and keeps working after they leave. Each operation needs one scope:

• read Look up templates and other workspace data. Contact details stay masked.
• read:pii See full contact details: email addresses, phone numbers and custom fields. Never on by default.
• write Create and change drafts: templates, campaigns, contacts, lists, flows. Sends nothing.
• publish Put things live that send nothing by themselves, such as a signup form. Never on by default.
• send Send campaigns and turn on flows. Reaches real people. Never on by default.
• webhooks Add, change, test and remove webhook endpoints. Reading them needs read only. Never on by default.

New keys get read and write. Nobody can give a key a scope their own role could not use. Keys made before the REST API act as the person who made them, with read and write limited by that person's role, and stop working if they leave the workspace.

/v1 is the major version. Within it, the Envoi-Version header picks a dated version. A key is pinned to the version of its first request, so behaviour only changes when you send a newer date. Every response says which version served it. Released: 2026-10-01 (latest 2026-10-01). An unknown date is refused with 400. A deprecated version keeps working for at least 12 months and says so with Deprecation and Sunset headers; after its sunset date it answers 410.

• JSON in and out. Field names are snake_case; an email document (blocks, variables, global_styles) keeps the builder's own format, so a template read here can be written back unchanged. A field the endpoint does not know is refused, never ignored.
• Lists are newest first, 25 per page by default and at most 100 (limit). Pass next_cursor back as cursor while has_more is true. Pages never skip or repeat an item, even while items are added.
• Creates and sends need an Idempotency-Key. Retrying with the same key and body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of doing it twice. The same key with a different body is refused with 422; while the first request is still running, 409.
• Drafts carry a version, also sent as the ETag. A write needs it back as If-Match: without it, 428; if someone changed the draft since, 412 with the current_version, and nothing is saved.
• A write's answer lists in warnings anything Envoi changed in what you sent to make it a valid email, such as a dropped unknown field.
• Each key has a per-minute limit (set on the key) and each workspace a shared one. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit, 429 with Retry-After.
• Every response has a Request-Id header. Quote it to support.

Every error is application/problem+json (RFC 9457) with a stable code, the param at fault when there is one, the request_id, a doc_url pointing below, and a next_action saying what to do. Internal errors never include details.

HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "type": "https://envoi.email/api-docs#error-precondition_failed",
  "title": "Version has changed",
  "status": 412,
  "detail": "The template changed since you read it. Nothing was saved.",
  "code": "precondition_failed",
  "param": "If-Match",
  "request_id": "req_4f1c0a9e2b7d6c3a1e5f8b90",
  "doc_url": "https://envoi.email/api-docs#error-precondition_failed",
  "next_action": "Read template tpl_123 again, re-apply your change to it, and send its new version as If-Match.",
  "current_version": "9b1e..."
}

missing_api_key 401 API key required

Send Authorization: Bearer <API key>.

invalid_api_key 401 Invalid API key

The key is wrong, revoked or expired. Create or rotate one in Settings, API keys.

key_not_workspace_scoped 403 API key has no workspace

An old key with no workspace. Create a new key in the workspace you want to use.

key_owner_not_member 403 API key's creator left the workspace

An older key acts as the person who made it, and they have left the workspace. Create a new key: new keys belong to the workspace.

insufficient_scope 403 API key is missing a scope

The key lacks the scope named in required_scope. An owner or admin can add it in Settings, API keys.

insufficient_permission 403 Your role does not allow this

An older key is limited by its creator's role, and that role cannot do this.

invalid_request 400 Invalid request

A field is missing, the wrong type, or not one the endpoint knows. param names it.

invalid_json 400 Request body is not valid JSON

The body is not valid JSON.

invalid_cursor 400 Invalid cursor

Pass next_cursor exactly as a list returned it, to the same endpoint.

unsupported_api_version 400 Unsupported API version

Envoi-Version must be a released version. supported_versions lists them.

api_version_sunset 410 API version retired

That version is retired. Send a newer Envoi-Version.

resource_missing 404 Not found

Nothing with that id in this workspace.

payload_too_large 413 Request body too large

Bodies are limited to 1 MB.

unsupported_media_type 415 Request body must be JSON

Send Content-Type: application/json.

idempotency_key_required 400 Idempotency-Key required

Creates and sends need an Idempotency-Key header: any unique string up to 255 characters.

invalid_idempotency_key 400 Invalid Idempotency-Key

Use up to 255 printable ASCII characters, no spaces.

idempotency_conflict 422 Idempotency-Key reused with a different request

That Idempotency-Key was already used by another key, with a different body, or on another endpoint. Use a new key for a new request.

idempotency_in_flight 409 Request with this Idempotency-Key is still running

The first request with this key is still running. Retry with the same key after Retry-After.

idempotency_result_unavailable 409 Request already ran; its response was not stored

The request with this key already ran, but its response could not be stored. Read the resource to see what it did; do not retry it.

precondition_required 428 If-Match required

Writes to a draft need If-Match with the version (the ETag) you last read.

precondition_failed 412 Version has changed

Someone changed it since you read it, and nothing was saved. Read it again, re-apply your change, and send the new version.

rate_limited 429 Too many requests

Wait for Retry-After seconds. limit_scope says whether the key, the workspace, or the key’s reports (analytics, 60 a minute) hit their limit.

conflict 409 Conflicts with the current state

The object is not in a state that allows this, such as a campaign that is no longer a draft or a live flow whose steps you tried to change. detail says which.

work_session_expired 410 Work session expired

The ws_ session went 30 days without use. detail names the tool that reopens it; the draft is kept.

work_session_closed 409 Work session closed

The ws_ session was finished or abandoned. Start a new one on the same object.

send_blocked 409 Not ready to send

Something stops the send or the flow going live. blockers lists each one and who can fix it; the campaign or flow check shows them all.

setup_incomplete 409 Workspace setup not finished

The workspace has not finished its setup: its domain, sender or business details. missing lists each row with where it is fixed; a person finishes them at setup_url. Nothing was sent.

list_source_missing 409 A list in the audience has no answered source

The campaign reaches people on a list nobody has said the source of. lists names each one (id and name), and detail says the same in words. A teammate answers how those people joined from the list in Envoi (Answer for this list); an API key or agent cannot. Checked after setup_incomplete. Nothing was sent.

publish_blocked 409 Not ready to publish

The form is not fit to go live. blockers lists each one and who can fix it; form_check shows them all.

approval_required 403 Approval required

A person must approve this send or flow. Ask with POST /approvals and share the link it returns.

approval_unusable 409 Approval cannot be used

The approval cannot be used: already used, rejected, voided by an edit, over its recipient cap, or outside its window. reason says which.

approval_expired 410 Approval expired

Approvals last 24 hours. Ask for a new one.

agent_send_cap 403 Agent send limit reached

This agent reached the workspace's daily limit for sends without approval. Ask a person to approve it.

agent_unsubscribe_cap 403 Agent unsubscribe limit reached

API keys and agents can unsubscribe at most 100 subscribed people in a workspace in any 24 hours, across contact writes and imports. Nothing in the request was changed. A teammate can unsubscribe more people in Envoi.

confirmation_required 409 Confirm the recipient count

Repeat the exact count to go ahead without a person approving it: recipient_count as confirm_recipients for a send, entrants as confirm_entrants for a flow.

send_worker_updating 503 Send worker is updating

Envoi is deploying its send worker, which must be on the current release before an approved send can go out. Nothing was sent. Retry in a few minutes.

storage_not_configured 503 Media storage not configured

Media storage is not set up on this Envoi instance.

email_provider_error 502 Email provider refused the message

The email provider did not accept a test message, so nothing was sent and the campaign is unchanged. Retry shortly; provider_code names the provider’s reason when it gave one.

range_too_wide 400 Date range too wide

A report reads at most about three years, and a grouped series at most 100 points. Shorten the range, or group by a longer period.

report_timeout 503 Report took too long

The report ran past its time limit and was stopped. Ask for less: a shorter range, a longer group_by, fewer metrics, or no compare or people.

validation_error 400 Invalid request

The request was well formed but not allowed. detail says why.

usage_limit_exceeded 402 Plan limit reached

The workspace's plan limit for this is used up.

unverified_sender 400 Sender not verified

Send from a domain verified in this workspace.

url_blocked 400 URL not allowed

That URL points somewhere Envoi will not fetch, such as a private address.

domain_rejected 400 Domain rejected

That domain cannot be used for sending.

domain_already_registered 409 Domain already registered

That domain is already registered to a workspace.

domain_provider_unavailable 503 Domain provider unavailable

The domain provider did not answer. Try again shortly.

agentmail_not_configured 503 Inbound email not configured

Inbound email is not set up on this Envoi instance.

inbox_provider_not_configured 503 Inbound email not configured

Inbound email is not set up on this Envoi instance.

internal_error 500 Internal error

Our fault. Retry, and quote request_id to support if it keeps happening.

• contact.created Someone was added in Envoi, by a form (once they confirm, with double opt-in), or through the API or an agent. data: contact_id, status, source.
• contact.updated A contact was changed in Envoi or through the API. Names the fields that changed, never their values. data: contact_id, changed, source.
• contact.unsubscribed A contact opted out of email: the unsubscribe link, one-click, the preferences page, a teammate, the API, or an import or Shopify sync that turned a subscribed contact to unsubscribed. data: contact_id, channel, source, campaign_id.
• campaign.sent An email or SMS campaign finished sending to everyone it was sent to. data: campaign_id, channel, name, recipients, failed, sent_at.
• form.submitted A signup form was submitted. What the visitor typed is not included. data: form_id, submission_id, contact_id, contact_created.
• flow.contact_entered A contact started a flow. data: flow_id, contact_id, execution_id, trigger_step_id.
• flow.contact_exited A contact finished a flow, reached its goal, stopped at a step that failed, placed an order in a flow set to exit on one, or texted STOP to a question. data: flow_id, contact_id, execution_id, reason.
• approval.requested Someone, or an agent, asked a teammate to approve a send, a flow going live, or another action. data: approval_id, action_type, subject_type, subject_id, requested_by, expires_at.
• approval.decided An approval was approved or rejected, by a teammate or by the workspace policy for agent sends. data: approval_id, action_type, subject_type, subject_id, decision, decided_by.
• sms.opted_out A phone number opted out of texts: a STOP reply, a teammate recording it, or an import, Klaviyo migration or Shopify sync that withdrew an opt-in on record. data: contact_id, brand_id, scope, source.

Payloads name things by id. They never carry an email address, a phone number, a name, a custom field value or what a visitor typed into a form: read those with the REST API if you need them. An endpoint can opt in to the contact's email, phone and name on contact events (include_contact_details), which only someone who could read them through the API may turn on: a teammate who can export contacts, or a key with read:pii. If that person leaves or loses the role, or the key is revoked, the details stop and data.contact_details_withheld is true.

Headers follow Standard Webhooks: webhook-id (the event id, the same on every retry), webhook-timestamp (when this attempt was signed, in Unix seconds) and webhook-signature. The body is { id, type, timestamp, data }.

POST /envoi-webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Envoi-Webhooks/1.0 (+https://envoi.email/api-docs#webhooks)
webhook-id: evt_5f2c1e0b9a8d7c6b5a4f3e2d1c0b9a8d
webhook-timestamp: 1790000000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_5f2c1e0b9a8d7c6b5a4f3e2d1c0b9a8d",
  "type": "form.submitted",
  "timestamp": "2026-09-21T14:13:20.000Z",
  "data": {
    "form_id": "cmf0form0001",
    "submission_id": "cmf0subm0001",
    "contact_id": "cmf0cont0001",
    "contact_created": true
  }
}

The signature is an HMAC-SHA256, keyed with the base64 part of your secret, over id.timestamp.body, sent as v1,<base64>. Check it against the raw body before you parse it. Any Standard Webhooks library works; this is the whole check in Node with no packages:

import crypto from 'node:crypto';

// secret: the whsec_... value Envoi showed once, when you added the endpoint.
// rawBody: the request body exactly as it arrived, before any JSON parsing.
function verifyEnvoiWebhook(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) return false;

  // A request signed more than 5 minutes ago (or ahead) may be a replay.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  // After a rotation there are two signatures for 24 hours: either may match.
  return signatures.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    if (version !== 'v1' || !signature) return false;
    const given = Buffer.from(signature, 'base64');
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

app.post('/envoi-webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verifyEnvoiWebhook(process.env.ENVOI_WEBHOOK_SECRET, req.headers, rawBody)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(rawBody);
  // Delivery is at least once: skip an event.id you have already handled.
  // Answer within 10 seconds; do slow work after responding.
  res.sendStatus(204);
});

The secret is shown once, when the endpoint is added. Rotating it returns a new one, and for the next 24 hours every request carries two signatures, one per secret, separated by a space, so you can deploy the new secret without dropping a delivery. A second rotation inside those 24 hours is refused (409, with the time it is allowed again), so the first secret is never dropped early.

• Answer with any 2xx within 10 seconds, the connection opened within 3. Anything else is a failure, including a redirect, which is never followed. Envoi records the status code, never your response body.
• A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, then 2, 5, 8 and 8 hours: eight attempts over about 24 hours. Each delivery is independent, and they can arrive out of order.
• Delivery is at least once. Keep the id of events you have handled and skip a repeat.
• After 5 failed attempts in a row, Envoi pauses the endpoint: its waiting deliveries are held, then a single attempt tests it, and the pause grows after each failure. The first success sends everything that waited.
• When every attempt has failed for about a day, Envoi turns the endpoint off and tells the workspace owner in Activity. Turn it back on in Settings, Webhooks, after a test succeeds.
• Settings, Webhooks shows each endpoint's deliveries for 30 days, with the status code and error of the last attempt, and retries a failed one on request.