API Documentation & Integrations

Get the authenticated API key + workspace

GET /api/v1/me

Returns the API key and workspace that the Bearer token belongs to, including the key's granted scopes, plus the account's current standing. Useful for verifying a key, discovering its permissions, and checking whether the account can send before you attempt any write. The billing block is present only when the account is suspended over an outstanding invoice. This is the one endpoint whose response is NOT wrapped in the standard data envelope.

• Required scope: none (any valid key)

Response — 200

{
  "apiKey": {
    "id": "key_8f1c2a",
    "name": "Production integration",
    "scopes": [
      "mailboxes:read",
      "mailboxes:write",
      "warmup:read"
    ]
  },
  "workspace": {
    "id": "ws_4b9d10"
  },
  "account_status": "suspended",
  "account_status_label": "Suspended — an invoice is outstanding",
  "account_suspended": true,
  "can_send": false,
  "billing": {
    "reason": "An invoice on the account has not been settled yet.",
    "what_to_do": "Settle the outstanding invoice and sending resumes automatically.",
    "amount_outstanding": "$32.99",
    "amount_outstanding_cents": 3299,
    "currency": "USD",
    "invoice_number": "B1C2D3-0004",
    "pay_url": "https://invoice.stripe.com/i/...",
    "since": "2026-07-29T12:52:00.000Z"
  }
}

Errors

• 401 unauthorized — Missing or invalid API key.

Get the cold email footer settings

GET /api/v1/workspace/settings

Returns the postal address printed in the footer of your cold email, how people opt out of it, and the exact sentence the footer will show. "link": The footer carries an Unsubscribe link — on your own verified tracking domain when you have one, otherwise on a shared WarmySender domain. "reply": The footer reads “Reply "unsubscribe" to opt out” and points back at the sending mailbox — no third-party link at all. Either way, a reply asking to unsubscribe is honored automatically and that person is never contacted again. Writing your own sentence? Put the word in quotes — like Reply “stop” — and a reply of just that word is honored too. opt_out_text is your own wording, or null when you have not set any; opt_out_text_effective is what the footer actually shows.

• Required scope: campaigns:read

Response — 200

{
  "data": {
    "company_address": "120 Market Street, Suite 400, San Francisco, CA 94105",
    "opt_out_style": "link",
    "opt_out_text": null,
    "opt_out_text_effective": "Unsubscribe"
  }
}

Errors

• 403 insufficient_scope — The key lacks campaigns:read.
• 404 not_found — The workspace no longer exists.

Update the cold email footer settings

PATCH /api/v1/workspace/settings

Change the postal address printed in the footer of your cold email, the way people opt out, the wording of the opt-out sentence, or any combination. Send at least one field; anything you leave out is unchanged. This changes what the footer says only — it sends nothing and changes no sending limit.

• Required scope: campaigns:write

Request body

• company_address — type: string — optional — range: –1000. The postal address shown in the footer of your cold email. Send an empty string to clear it.
• opt_out_style — type: string — optional — one of: link, reply. How people opt out of your cold email. "link": The footer carries an Unsubscribe link — on your own verified tracking domain when you have one, otherwise on a shared WarmySender domain. "reply": The footer reads “Reply "unsubscribe" to opt out” and points back at the sending mailbox — no third-party link at all. Either way, a reply asking to unsubscribe is honored automatically and that person is never contacted again. Writing your own sentence? Put the word in quotes — like Reply “stop” — and a reply of just that word is honored too.
• opt_out_text — type: string — optional — range: –120. The sentence recipients click or reply to in order to opt out — written in your own words, 4–120 characters, one line. Send an empty string to go back to the default for your opt-out style ("Unsubscribe" for link, "Reply "unsubscribe" to opt out" for reply). Put {{opt_out}} inside an email or signature to place the sentence yourself.

Request example

{
  "company_address": "120 Market Street, Suite 400, San Francisco, CA 94105",
  "opt_out_style": "reply",
  "opt_out_text": "Reply \"stop\" and we will not write again"
}

Response — 200

{
  "data": {
    "company_address": "120 Market Street, Suite 400, San Francisco, CA 94105",
    "opt_out_style": "reply",
    "opt_out_text": "Reply \"stop\" and we will not write again",
    "opt_out_text_effective": "Reply \"stop\" and we will not write again"
  }
}

• Either way, a reply asking to unsubscribe is honored automatically and that person is never contacted again. Writing your own sentence? Put the word in quotes — like Reply “stop” — and a reply of just that word is honored too.
• Sending an empty string for company_address clears the address.
• Sending an empty string for opt_out_text goes back to the default for your style ("Unsubscribe" for link, "Reply "unsubscribe" to opt out" for reply).
• Custom wording changes what the opt-out says, never whether one appears — every cold email carries one.

Errors

• 400 validation_error — No field was supplied, an unknown field was sent, opt_out_style was not "link" or "reply", or opt_out_text was too short, too long, or worded in a way that would not read as an opt-out.
• 403 insufficient_scope — The key lacks campaigns:write.
• 404 not_found — The workspace no longer exists.

List mailboxes

GET /api/v1/mailboxes

Returns connected mailboxes, newest first, with cursor pagination. Soft-deleted mailboxes are excluded unless you filter by status=deleted.

• Required scope: mailboxes:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.
• external_id — in: query — type: string — optional. Exact-match filter on your external_id.
• email_address — in: query — type: string — optional. Case-insensitive substring match on the email address.
• status — in: query — type: string — optional — one of: created, testing, connected, error, deleted. Filter by status.
• warmup_enabled — in: query — type: string — optional — one of: true, false. Filter by warmup on/off.

Response — 200

{
  "data": [
    {
      "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
      "external_id": "crm-contact-8841",
      "email_address": "[email protected]",
      "display_name": "Jordan Lee",
      "status": "connected",
      "health_status": "ok",
      "health_reasons": null,
      "read_channel_state": "ok",
      "read_channel_verified": true,
      "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
      "read_channel_state_label": "Inbox readable",
      "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
      "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
      "warmup_enabled": true,
      "warmup_type": "normal",
      "warmup_progress": 62,
      "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
      "incoming_warmup_state": "receiving",
      "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
      "incoming_warmup_paused": false,
      "incoming_warmup_pause_needs_review": false,
      "incoming_warmup_resumes_at": null,
      "domain_blocked_for_incoming_warmup": false,
      "last_received_at": "2026-06-10T07:58:00.000Z",
      "days_since_last_received": 0,
      "sending_enabled": true,
      "daily_send_limit": 50,
      "last_tested_at": "2026-06-10T08:31:00.000Z",
      "last_test_error": null,
      "signature": null,
      "created_at": "2026-06-06T10:43:01.357Z",
      "updated_at": "2026-06-10T08:31:05.220Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Get a mailbox

GET /api/v1/mailboxes/{id}

Fetch a single mailbox by id. Poll this after create/restore until status becomes "connected". The response also carries the incoming-warmup fields (`incoming_warmup_state` and friends) describing whether warmup is actually arriving at this mailbox, and the read-channel fields (`read_channel_state` and friends) describing whether we can open the mailbox and read it at all. `status` and `health_status` cover the sending side only — a mailbox can be "connected" and "ok" while its inbox cannot be opened, so check `read_channel_state` before concluding a mailbox is fully working.

• Required scope: mailboxes:read

Parameters

• id — in: path — type: string — required. Mailbox id (UUID).

Response — 200

{
  "data": {
    "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "external_id": "crm-contact-8841",
    "email_address": "[email protected]",
    "display_name": "Jordan Lee",
    "status": "connected",
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
    "warmup_enabled": true,
    "warmup_type": "normal",
    "warmup_progress": 62,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "sending_enabled": true,
    "daily_send_limit": 50,
    "last_tested_at": "2026-06-10T08:31:00.000Z",
    "last_test_error": null,
    "signature": null,
    "created_at": "2026-06-06T10:43:01.357Z",
    "updated_at": "2026-06-10T08:31:05.220Z"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 404 not_found — No mailbox with that id in your workspace.

Create a mailbox

POST /api/v1/mailboxes

Adds a mailbox and runs an asynchronous connection test (status moves created → testing → connected or error). If the email matches a previously soft-deleted mailbox, that mailbox is restored instead and the response is 200 with its preserved warmup history (otherwise 201).

• Required scope: mailboxes:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Request body

• email_address — type: string — required — format: email. The mailbox email address.
• smtp_host — type: string — required. SMTP server hostname, e.g. smtp.gmail.com.
• smtp_port — type: integer — optional — default: 587 — range: 1–65535. SMTP port. One of 25, 465, 587. Defaults to 587.
• smtp_username — type: string — required. SMTP login (usually the email address).
• smtp_password — type: string — required — format: password. SMTP password or app password.
• imap_host — type: string — required. IMAP server hostname, e.g. imap.gmail.com.
• imap_port — type: integer — optional — default: 993 — range: 1–65535. IMAP port. One of 143, 993. Defaults to 993.
• imap_username — type: string — required. IMAP login (usually the email address).
• imap_password — type: string — required — format: password. IMAP password or app password.
• external_id — type: string — optional — range: –255. Your own reference id for this mailbox (unique per workspace).
• display_name — type: string — optional — range: –255. Display name shown on outgoing mail.
• sending_enabled — type: boolean — optional — default: true. Whether the mailbox may send. Defaults to true.
• daily_send_limit — type: integer — optional — default: 50 — range: 1–1000. Max sends per day. Defaults to 50.
• auto_enable_warmup — type: boolean — optional — default: false. Enable warmup automatically once the connection test passes.

Request example

{
  "email_address": "[email protected]",
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "smtp_username": "[email protected]",
  "smtp_password": "app-password",
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "imap_username": "[email protected]",
  "imap_password": "app-password",
  "external_id": "crm-contact-8841",
  "auto_enable_warmup": true
}

Response — 201

{
  "data": {
    "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "external_id": "crm-contact-8841",
    "email_address": "[email protected]",
    "display_name": "Jordan Lee",
    "status": "testing",
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
    "warmup_enabled": true,
    "warmup_type": "normal",
    "warmup_progress": 0,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "sending_enabled": true,
    "daily_send_limit": 50,
    "last_tested_at": null,
    "last_test_error": null,
    "signature": null,
    "created_at": "2026-06-06T10:43:01.357Z",
    "updated_at": "2026-06-10T08:31:05.220Z"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }
}

• Send a unique Idempotency-Key header so retries never create duplicates.
• Connection test runs in the background — poll GET /mailboxes/{id} until status is "connected".
• A newly created mailbox reports read_channel_state "not_tested" until we have actually opened its inbox. That is not a failure — it means we have no evidence either way yet, so do not treat it as confirmation that replies will be seen.

Errors

• 400 validation_error — Body failed validation.
• 403 mailbox_limit_exceeded — At or above your plan's mailbox limit.
• 409 duplicate_email — An active mailbox already uses this email.
• 409 duplicate_external_id — The external_id is already in use.
• 422 ssrf_blocked — A host resolved to a private/internal IP.
• 422 invalid_port — A port outside the allowed list (25/465/587/143/993).

Test credentials (no save)

POST /api/v1/mailboxes/test

Synchronously tests SMTP + IMAP credentials WITHOUT creating a mailbox. Rate limited.

• Required scope: mailboxes:write
• Subject to a stricter per-endpoint connection-test rate limit.

Request body

• email_address — type: string — required — format: email. The mailbox email address.
• smtp_host — type: string — required. SMTP server hostname, e.g. smtp.gmail.com.
• smtp_port — type: integer — optional — default: 587 — range: 1–65535. SMTP port. One of 25, 465, 587. Defaults to 587.
• smtp_username — type: string — required. SMTP login (usually the email address).
• smtp_password — type: string — required — format: password. SMTP password or app password.
• imap_host — type: string — required. IMAP server hostname, e.g. imap.gmail.com.
• imap_port — type: integer — optional — default: 993 — range: 1–65535. IMAP port. One of 143, 993. Defaults to 993.
• imap_username — type: string — required. IMAP login (usually the email address).
• imap_password — type: string — required — format: password. IMAP password or app password.

Request example

{
  "email_address": "[email protected]",
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "smtp_username": "[email protected]",
  "smtp_password": "app-password",
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "imap_username": "[email protected]",
  "imap_password": "app-password"
}

Response — 200

{
  "data": {
    "smtp_ok": true,
    "imap_ok": true
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

• port_corrected and original_port appear only when an SMTP port fallback succeeded.

Errors

• 400 validation_error — Body failed validation.
• 422 ssrf_blocked — A host resolved to a private/internal IP.

Update a mailbox

PATCH /api/v1/mailboxes/{id}

Partial update — only the fields you send change. Changing SMTP/IMAP credentials re-runs the connection test. Set external_id or signature to null to clear them.

• Required scope: mailboxes:write

Parameters

• id — in: path — type: string — required. Mailbox id (UUID).

Request body

• display_name — type: string — optional — range: –255. Display name.
• smtp_host — type: string — optional. SMTP host.
• smtp_port — type: integer — optional — range: 1–65535. SMTP port (25/465/587).
• smtp_username — type: string — optional. SMTP login.
• smtp_password — type: string — optional — format: password. SMTP password.
• imap_host — type: string — optional. IMAP host.
• imap_port — type: integer — optional — range: 1–65535. IMAP port (143/993).
• imap_username — type: string — optional. IMAP login.
• imap_password — type: string — optional — format: password. IMAP password.
• sending_enabled — type: boolean — optional. Allow sending.
• daily_send_limit — type: integer — optional — range: 1–1000. Daily send cap.
• external_id — type: string — optional — nullable — range: –255. Your reference id, or null to clear.
• signature — type: string — optional — nullable — range: –65536. HTML/text signature, or null to clear.

Request example

{
  "display_name": "Jordan Lee",
  "daily_send_limit": 80
}

Response — 200

{
  "data": {
    "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "external_id": "crm-contact-8841",
    "email_address": "[email protected]",
    "display_name": "Jordan Lee",
    "status": "connected",
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
    "warmup_enabled": true,
    "warmup_type": "normal",
    "warmup_progress": 62,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "sending_enabled": true,
    "daily_send_limit": 80,
    "last_tested_at": "2026-06-10T08:31:00.000Z",
    "last_test_error": null,
    "signature": null,
    "created_at": "2026-06-06T10:43:01.357Z",
    "updated_at": "2026-06-10T08:31:05.220Z"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 400 validation_error — Body failed validation.
• 404 not_found — Mailbox not found.
• 409 duplicate_external_id — The new external_id is already in use.
• 422 ssrf_blocked — A host resolved to a private/internal IP.

Delete (soft) a mailbox

DELETE /api/v1/mailboxes/{id}

Soft-deletes the mailbox: it stops sending and warmup immediately but its history is preserved so it can be restored. Returns 200 with the mailbox object (status "deleted") — not 204.

• Required scope: mailboxes:write

Parameters

• id — in: path — type: string — required. Mailbox id (UUID).

Response — 200

{
  "data": {
    "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "external_id": "crm-contact-8841",
    "email_address": "[email protected]",
    "display_name": "Jordan Lee",
    "status": "deleted",
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
    "warmup_enabled": false,
    "warmup_type": "normal",
    "warmup_progress": 62,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "sending_enabled": true,
    "daily_send_limit": 50,
    "last_tested_at": "2026-06-10T08:31:00.000Z",
    "last_test_error": null,
    "signature": null,
    "created_at": "2026-06-06T10:43:01.357Z",
    "updated_at": "2026-06-10T08:31:05.220Z"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 404 not_found — Mailbox not found (or already deleted).

Restore a deleted mailbox

POST /api/v1/mailboxes/{id}/restore

Brings a soft-deleted mailbox back with its warmup history intact and re-runs the connection test (status returns to "created" → "connected"). Warmup starts disabled; enable it once connected. Blocked if an active mailbox already uses the same email.

• Required scope: mailboxes:write

Parameters

• id — in: path — type: string — required. Mailbox id (UUID).

Response — 200

{
  "data": {
    "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "external_id": "crm-contact-8841",
    "email_address": "[email protected]",
    "display_name": "Jordan Lee",
    "status": "created",
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
    "warmup_enabled": false,
    "warmup_type": "normal",
    "warmup_progress": 62,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "sending_enabled": true,
    "daily_send_limit": 50,
    "last_tested_at": "2026-06-10T08:31:00.000Z",
    "last_test_error": null,
    "signature": null,
    "created_at": "2026-06-06T10:43:01.357Z",
    "updated_at": "2026-06-10T08:31:05.220Z"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

• Poll GET /mailboxes/{id} until status is "connected".

Errors

• 404 not_found — No soft-deleted mailbox with that id.
• 409 duplicate_email — An active mailbox already uses this email.

Re-test a mailbox connection

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

Re-runs the connection test against the stored credentials and updates the mailbox status. Rate limited. The mailbox status reflects the SENDING side only — a problem reading the inbox is reported in test_result.read_channel and never stops the mailbox from sending.

• Required scope: mailboxes:write
• Subject to a stricter per-endpoint connection-test rate limit.

Parameters

• id — in: path — type: string — required. Mailbox id (UUID).

Response — 200

{
  "data": {
    "mailbox": {
      "id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
      "external_id": "crm-contact-8841",
      "email_address": "[email protected]",
      "display_name": "Jordan Lee",
      "status": "connected",
      "health_status": "ok",
      "health_reasons": null,
      "read_channel_state": "ok",
      "read_channel_verified": true,
      "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
      "read_channel_state_label": "Inbox readable",
      "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
      "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree",
      "warmup_enabled": true,
      "warmup_type": "normal",
      "warmup_progress": 62,
      "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
      "incoming_warmup_state": "receiving",
      "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
      "incoming_warmup_paused": false,
      "incoming_warmup_pause_needs_review": false,
      "incoming_warmup_resumes_at": null,
      "domain_blocked_for_incoming_warmup": false,
      "last_received_at": "2026-06-10T07:58:00.000Z",
      "days_since_last_received": 0,
      "sending_enabled": true,
      "daily_send_limit": 50,
      "last_tested_at": "2026-06-10T08:31:00.000Z",
      "last_test_error": null,
      "signature": null,
      "created_at": "2026-06-06T10:43:01.357Z",
      "updated_at": "2026-06-10T08:31:05.220Z"
    },
    "test_result": {
      "smtp_ok": true,
      "imap_ok": true,
      "read_channel": {
        "state": "ok",
        "verified": true,
        "code": null
      }
    }
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

• read_channel.state is one of ok | auth_failed | blocked_by_provider | not_tested. not_tested means we could not run the read test (for example a mailbox connected by sign-in rather than by password, which stores no reading password) — it is NOT a failure and NOT a pass.
• imap_ok is true only when the read test actually passed, so it is false for a not_tested result. Read read_channel.state when you need to tell those two apart.

Errors

• 404 not_found — Mailbox not found.
• 422 ssrf_blocked — A host resolved to a private/internal IP.

List warmup stats

GET /api/v1/warmup/stats

Per-mailbox warmup health in BOTH directions: sending-side progress, today's volume, placement and reputation, plus the incoming side — whether warmup is actually arriving at the mailbox (`incoming_warmup_state`), when it last did, and whether it is paused and why. `inbox_rate` measures the SENDING side only; `inbox_rate_measures` spells that out so the two are never conflated. Cursor paginated.

• Required scope: warmup:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.
• mailbox_id — in: query — type: string — optional. One mailbox id, or comma-separated ids (up to 100), to filter.

Response — 200

{
  "data": [
    {
      "mailbox_id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
      "email_address": "[email protected]",
      "warmup_enabled": true,
      "warmup_type": "normal",
      "warmup_mode": "new_mailbox",
      "warmup_mode_reason": "Strategy set by you.",
      "warmup_progress": 62,
      "warmup_target_daily_volume": 50,
      "effective_daily_limit": 50,
      "effective_limit_reason": null,
      "sent_today": 18,
      "received_today": 17,
      "reputation_score": 96,
      "inbox_rate": 98,
      "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
      "inbox_rate_sample": 240,
      "inbox_rate_reliable": true,
      "inbox_rate_sample_measures": "how many of this mailbox's sent warmup emails we confirmed the placement of — at 0 the rate above is a placeholder default, not a result",
      "spam_rate": 1,
      "last_sent_at": "2026-06-10T09:12:00.000Z",
      "incoming_warmup_state": "receiving",
      "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
      "incoming_warmup_paused": false,
      "incoming_warmup_pause_needs_review": false,
      "incoming_warmup_resumes_at": null,
      "domain_blocked_for_incoming_warmup": false,
      "last_received_at": "2026-06-10T07:58:00.000Z",
      "days_since_last_received": 0,
      "health_status": "ok",
      "health_reasons": null,
      "read_channel_state": "ok",
      "read_channel_verified": true,
      "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
      "read_channel_state_label": "Inbox readable",
      "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
      "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Get warmup stats for one mailbox

GET /api/v1/warmup/stats/{mailboxId}

Warmup health for a single mailbox, in both directions: the sending side (volume, placement, reputation) and the incoming side (`incoming_warmup_state`, `last_received_at`, and a plain-language `incoming_warmup_state_detail` explaining any pause).

• Required scope: warmup:read

Parameters

• mailboxId — in: path — type: string — required. Mailbox id (UUID).

Response — 200

{
  "data": {
    "mailbox_id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "email_address": "[email protected]",
    "warmup_enabled": true,
    "warmup_type": "normal",
    "warmup_mode": "new_mailbox",
    "warmup_mode_reason": "Strategy set by you.",
    "warmup_progress": 62,
    "warmup_target_daily_volume": 50,
    "effective_daily_limit": 50,
    "effective_limit_reason": null,
    "sent_today": 18,
    "received_today": 17,
    "reputation_score": 96,
    "inbox_rate": 98,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "inbox_rate_sample": 240,
    "inbox_rate_reliable": true,
    "inbox_rate_sample_measures": "how many of this mailbox's sent warmup emails we confirmed the placement of — at 0 the rate above is a placeholder default, not a result",
    "spam_rate": 1,
    "last_sent_at": "2026-06-10T09:12:00.000Z",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 404 not_found — Mailbox not found.

Update warmup settings

PATCH /api/v1/warmup/settings/{mailboxId}

Enable/disable warmup, switch strategy, or set the target daily volume for one mailbox. Enabling requires the mailbox status to be "connected". A strategy change updates both `warmup_type` and `warmup_mode` (the field the ramp reads). If a faster strategy cannot take effect yet because recent deliverability is poor, the response carries a plain-language `meta.warning` — the change is recorded, but the safer pace stays in force until placement recovers.

• Required scope: warmup:write

Parameters

• mailboxId — in: path — type: string — required. Mailbox id (UUID).

Request body

• warmup_enabled — type: boolean — optional. Turn warmup on or off. Enabling requires the mailbox status to be "connected".
• warmup_type — type: string — optional — one of: new_domain, new_mailbox, dormant, maintenance, recovery, aggressive, normal, conservative. Warmup strategy. Controls ramp speed and target.
• warmup_target_daily_volume — type: integer — optional — range: 1–100. Target warmup emails per day once fully ramped.

Request example

{
  "warmup_enabled": true,
  "warmup_type": "normal",
  "warmup_target_daily_volume": 50
}

Response — 200

{
  "data": {
    "mailbox_id": "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "email_address": "[email protected]",
    "warmup_enabled": true,
    "warmup_type": "normal",
    "warmup_mode": "new_mailbox",
    "warmup_mode_reason": "Strategy set by you.",
    "warmup_progress": 62,
    "warmup_target_daily_volume": 50,
    "effective_daily_limit": 50,
    "effective_limit_reason": null,
    "sent_today": 18,
    "received_today": 17,
    "reputation_score": 96,
    "inbox_rate": 98,
    "inbox_rate_measures": "warmup this mailbox SENT that landed in recipients' inboxes — not what arrives here",
    "inbox_rate_sample": 240,
    "inbox_rate_reliable": true,
    "inbox_rate_sample_measures": "how many of this mailbox's sent warmup emails we confirmed the placement of — at 0 the rate above is a placeholder default, not a result",
    "spam_rate": 1,
    "last_sent_at": "2026-06-10T09:12:00.000Z",
    "incoming_warmup_state": "receiving",
    "incoming_warmup_state_detail": "Warmup is arriving at this mailbox normally.",
    "incoming_warmup_paused": false,
    "incoming_warmup_pause_needs_review": false,
    "incoming_warmup_resumes_at": null,
    "domain_blocked_for_incoming_warmup": false,
    "last_received_at": "2026-06-10T07:58:00.000Z",
    "days_since_last_received": 0,
    "health_status": "ok",
    "health_reasons": null,
    "read_channel_state": "ok",
    "read_channel_verified": true,
    "read_channel_verified_at": "2026-06-10T07:58:00.000Z",
    "read_channel_state_label": "Inbox readable",
    "read_channel_state_detail": "We have opened this mailbox and read what arrived, so replies and warmup confirmations can be seen.",
    "read_channel_measures": "whether we can open this mailbox and read what arrives — a separate check from whether it can send, and the two can disagree"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 400 validation_error — Body failed validation.
• 404 not_found — Mailbox not found.
• 422 mailbox_not_connected — Tried to enable warmup on a mailbox that is not connected.

Bulk-update warmup settings (async)

POST /api/v1/warmup/bulk-update

Applies the same warmup changes to many mailboxes at once. Returns 202 with a job id immediately — poll GET /jobs/{id} for progress. Mailboxes that can't be enabled (not connected) are recorded as per-item errors on the job. A strategy change updates both `warmup_type` and `warmup_mode` (the field the ramp reads) on every mailbox in the batch.

• Required scope: warmup:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Request body

• mailbox_ids — type: string[] — required — range: 1–500. Mailbox ids to update (1–500).
• updates — type: object — required. A warmup settings object — same fields as Update warmup settings (warmup_enabled, warmup_type, warmup_target_daily_volume). At least one field required.

Request example

{
  "mailbox_ids": [
    "5bd50e20-6b75-4429-9a5a-4a09b46e945a",
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "updates": {
    "warmup_enabled": true,
    "warmup_type": "normal"
  }
}

Response — 202

{
  "data": {
    "job_id": "job_7d2f1a",
    "status": "processing",
    "total_items": 2
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Errors

• 400 validation_error — Body failed validation or no update fields given.
• 404 mailboxes_not_found — One or more mailbox ids don't exist (details.missing_mailbox_ids).

Get job status

GET /api/v1/jobs/{id}

Status and progress of an asynchronous job (e.g. a warmup bulk-update). Per-item failures are listed in errors.

• Required scope: jobs:read

Parameters

• id — in: path — type: string — required. Job id (UUID).

Response — 200

{
  "data": {
    "id": "job_7d2f1a",
    "type": "bulk_warmup_update",
    "status": "completed",
    "total_items": 2,
    "processed_items": 2,
    "failed_items": 0,
    "errors": [],
    "created_at": "2026-06-10T12:00:00.000Z",
    "completed_at": "2026-06-10T12:00:04.000Z"
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 404 not_found — Job not found.

List prospects

GET /api/v1/prospects

Returns prospects in your workspace with cursor pagination.

• Required scope: prospects:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.
• filter — in: query — type: string — optional. Repeatable metadata filter, formatted field:op:value (e.g. company:eq:Acme, custom:region:eq:US, email:exists). Fields: email, firstName, lastName, company, role, country, city, industry, globalStatus, tags, or custom:<key>. Ops: eq, neq, contains, exists. Unknown/invalid filters are ignored and echoed back in filters_ignored.

Response — 200

{
  "data": [
    {
      "id": "f3c4a2d1-9b7e-4c2a-8f10-2b6d5e8a1c44",
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Doe",
      "company": "Acme Inc",
      "role": "CTO",
      "phone": null,
      "globalStatus": "active",
      "linkedinUrl": "https://www.linkedin.com/in/janedoe",
      "instagramUsername": "janedoe",
      "whatsappPhone": "491712345678",
      "customFields": {
        "plan": "enterprise"
      },
      "createdAt": "2026-06-09T14:02:00.000Z",
      "updatedAt": "2026-06-09T14:02:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Create a prospect

POST /api/v1/prospects

Creates a prospect. Provide at least one of email, linkedinUrl, instagramUsername, or whatsappPhone — a prospect with no email address is still created and can be enrolled in LinkedIn, Instagram or WhatsApp campaigns. If one with the same email already exists it is merged and returned with alreadyExisted=true (HTTP 200); a brand-new prospect returns 201. Pass listId to drop the prospect into one of your lists; if a running campaign is linked to that list the prospect is auto-enrolled (continuous enrollment) — ideal for a website signup or popup form. Pass enrollInCampaignId instead to enroll into one specific campaign in the same call.

• Required scope: prospects:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Request body

• email — type: string — optional — format: email. Prospect email (unique per workspace). Optional — provide email, linkedinUrl, instagramUsername, or whatsappPhone.
• firstName — type: string — optional. First name.
• lastName — type: string — optional. Last name.
• company — type: string — optional. Company.
• role — type: string — optional. Job title / role.
• phone — type: string — optional. Phone number.
• linkedinUrl — type: string — optional — format: uri. LinkedIn profile URL. Use for a LinkedIn-only prospect with no email.
• instagramUsername — type: string — optional. Instagram handle (with or without the leading @, or a full instagram.com profile URL). Use for an Instagram-only prospect with no email.
• whatsappPhone — type: string — optional. WhatsApp number in any format (+49 171 234 5678, 0049…, bare digits, or a wa.me link). Stored in a single normalized form so the same person is never created twice. Use for a WhatsApp-only prospect with no email.
• customFields — type: object — optional. Arbitrary key/value pairs for personalization.
• listId — type: string — optional. Add the created/updated prospect to this list. When a running campaign is linked to the list, the prospect is auto-enrolled into it (continuous enrollment). Find the list ID on the Lists page.
• enroll — type: boolean — optional — default: true. When listId is set and a running campaign is linked to that list, auto-enroll the prospect into it. Set false to add to the list only, without enrolling. Defaults to true. Ignored when listId is omitted.
• enrollInCampaignId — type: string — optional. Enroll the created/updated prospect into this specific campaign in the same call (bypasses lists). Requires the enrollments:write scope. Suppressed prospects are skipped.

Request example

{
  "email": "[email protected]",
  "firstName": "Sam",
  "listId": "list_9f3a2b",
  "enroll": true
}

Response — 201

{
  "data": {
    "id": "f3c4a2d1-9b7e-4c2a-8f10-2b6d5e8a1c44",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Acme Inc",
    "role": "CTO",
    "phone": null,
    "globalStatus": "active",
    "linkedinUrl": "https://www.linkedin.com/in/janedoe",
    "instagramUsername": "janedoe",
    "whatsappPhone": "491712345678",
    "customFields": {
      "plan": "enterprise"
    },
    "createdAt": "2026-06-09T14:02:00.000Z",
    "updatedAt": "2026-06-09T14:02:00.000Z"
  },
  "alreadyExisted": false,
  "listId": "list_9f3a2b",
  "list": {
    "attached": true,
    "enrolledCampaigns": 1
  }
}

• The prospect is always saved even if list attach or enrollment can't complete — the outcome is reported in the list / enrollment fields rather than failing the call.
• listId echoes back the list you passed (or null), and list is { attached: true, enrolledCampaigns: <n> } on success, or { attached: false, error: "list_not_found", message: ... } if the list ID was wrong.
• enrolledCampaigns counts the running campaigns linked to the list that the prospect was just folded into.

Errors

• 400 validation_error — Body failed validation, or none of email, linkedinUrl, instagramUsername, or whatsappPhone was provided.
• 403 prospect_limit_reached — Workspace prospect limit reached.
• 200 list_not_found — listId did not match a list in your workspace. The prospect is still saved; see list.error in the response body.

Update a prospect

PATCH /api/v1/prospects/{id}

Partial update of a prospect. Accepts every field the in-app contact editor exposes except email (change the address in the app) and status (bounced / unsubscribed / do-not-contact cannot be lifted here). website, country, city, industry, tags and custom fields are included. linkedinUrl, instagramUsername and whatsappPhone may be set or cleared (null). A field name that is not on this list is refused and named in the error.

• Required scope: prospects:write

Parameters

• id — in: path — type: string — required. Prospect id (UUID).

Request body

• firstName — type: string — optional — nullable. First name, or null to clear.
• lastName — type: string — optional — nullable. Last name, or null to clear.
• company — type: string — optional — nullable. Company, or null to clear.
• role — type: string — optional — nullable. Role, or null to clear.
• phone — type: string — optional — nullable. Phone, or null to clear.
• linkedinUrl — type: string — optional — format: uri — nullable. LinkedIn URL, or null to clear.
• instagramUsername — type: string — optional — nullable. Instagram handle (with or without the leading @, or a full instagram.com profile URL), or null to clear.
• whatsappPhone — type: string — optional — nullable. WhatsApp number in any format, or null to clear. A number that cannot be read as a real phone number clears the field rather than being stored as typed.
• website — type: string — optional — nullable. Website.
• country — type: string — optional — nullable. Country.
• city — type: string — optional — nullable. City.
• industry — type: string — optional — nullable. Industry.
• tags — type: string[] — optional — nullable. Tags (replaces the existing set). A comma-separated string is also accepted; null or an empty list clears all tags.
• customFields — type: object — optional — nullable. Custom fields, merged per name. Names you omit are left unchanged. Set a name to null to remove that field. Send null for the whole object to remove every custom field. An empty object {} changes nothing.

Request example

{
  "role": "VP Engineering",
  "industry": "SaaS",
  "tags": [
    "vip"
  ],
  "customFields": {
    "plan": "enterprise"
  }
}

Response — 200

{
  "data": {
    "id": "f3c4a2d1-9b7e-4c2a-8f10-2b6d5e8a1c44",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Acme Inc",
    "role": "VP Engineering",
    "phone": null,
    "globalStatus": "active",
    "linkedinUrl": "https://www.linkedin.com/in/janedoe",
    "instagramUsername": "janedoe",
    "whatsappPhone": "491712345678",
    "customFields": {
      "plan": "enterprise"
    },
    "createdAt": "2026-06-09T14:02:00.000Z",
    "updatedAt": "2026-06-09T14:02:00.000Z"
  }
}

Errors

• 400 unknown_fields — The body included a field that cannot be updated. The response names those fields.
• 400 validation_error — Body failed validation.
• 404 not_found — Prospect not found.

Suppress prospects by email

POST /api/v1/prospects/suppress

Adds emails to your suppression list so those people are never contacted by any campaign. Existing prospects are marked suppressed.

• Required scope: suppressions:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Request body

• emails — type: string[] — required — range: 1–1000. Emails to suppress (1–1000).
• reason — type: string — optional. Optional reason stored with each entry.

Request example

{
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "reason": "manual opt-out"
}

Response — 200

{
  "data": {
    "suppressedCount": 2,
    "alreadySuppressedCount": 0,
    "notFoundCount": 0,
    "totalProcessed": 2
  }
}

Errors

• 400 validation_error — Body failed validation.

List suppression entries

GET /api/v1/suppressions

Returns suppressed emails and domains (the blocklist) with cursor pagination.

• Required scope: suppressions:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.
• type — in: query — type: string — optional — one of: email, domain. Filter by entry type.

Response — 200

{
  "data": [
    {
      "id": "sup_1a2b3c",
      "type": "email",
      "value": "[email protected]",
      "source": "api",
      "reason": "manual opt-out",
      "createdAt": "2026-06-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

List campaigns

GET /api/v1/campaigns

Returns campaigns with summary stats (sent/opened/replied/...). Cursor paginated.

• Required scope: campaigns:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.
• status — in: query — type: string — optional — one of: draft, scheduled, running, paused, completed, error. Filter by status.

Response — 200

{
  "data": [
    {
      "id": "c1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
      "name": "Q3 Outbound — Founders",
      "status": "draft",
      "channel": "email",
      "description": null,
      "timezone": "UTC",
      "dailySendLimit": 50,
      "sendingWindowStart": null,
      "sendingWindowEnd": null,
      "scheduleDays": null,
      "stopOnReply": true,
      "stopOnBounce": true,
      "stopOnUnsubscribe": true,
      "trackOpens": true,
      "trackClicks": true,
      "opt_out_style": null,
      "opt_out_text": null,
      "totalProspects": 0,
      "sent": 0,
      "opened": 0,
      "clicked": 0,
      "replied": 0,
      "bounced": 0,
      "unsubscribed": 0,
      "startDate": null,
      "endDate": null,
      "createdAt": "2026-06-10T12:00:00.000Z",
      "updatedAt": "2026-06-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Get a campaign (with steps)

GET /api/v1/campaigns/{id}

Returns a single campaign including its ordered steps array. Steps of type "condition" additionally carry conditionType, conditionTrueNext, conditionFalseNext, conditionTimeoutDays and conditions (read-only).

• Required scope: campaigns:read

Parameters

• id — in: path — type: string — required. Campaign id (UUID).

Response — 200

{
  "data": {
    "id": "c1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
    "name": "Q3 Outbound — Founders",
    "status": "draft",
    "channel": "email",
    "description": null,
    "timezone": "UTC",
    "dailySendLimit": 50,
    "sendingWindowStart": null,
    "sendingWindowEnd": null,
    "scheduleDays": null,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopOnUnsubscribe": true,
    "trackOpens": true,
    "trackClicks": true,
    "opt_out_style": null,
    "opt_out_text": null,
    "totalProspects": 0,
    "sent": 0,
    "opened": 0,
    "clicked": 0,
    "replied": 0,
    "bounced": 0,
    "unsubscribed": 0,
    "startDate": null,
    "endDate": null,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "updatedAt": "2026-06-10T12:00:00.000Z",
    "opt_out_effective": {
      "style": "link",
      "style_source": "workspace",
      "text": "Unsubscribe",
      "text_source": "default"
    },
    "steps": [
      {
        "id": "s1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
        "stepIndex": 0,
        "type": "email",
        "name": "Intro",
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}}, ...</p>",
        "bodyText": "Hi {{firstName}}, ...",
        "delayDays": 0,
        "delayHours": null,
        "isActive": true,
        "sendAsReply": null,
        "quotePreviousMessages": true,
        "sentCount": 0,
        "openCount": 0,
        "clickCount": 0,
        "replyCount": 0,
        "bounceCount": 0,
        "linkedinActionType": null,
        "linkedinMessageTemplate": null,
        "linkedinInviteNote": null,
        "linkedinSubject": null,
        "linkedinMaxWaitDays": null,
        "linkedinEngagementConfig": null,
        "linkedinInmailConfig": null
      },
      {
        "id": "s2b3c4d5-e6f7-48a9-b0c1-2d3e4f5a6b7c",
        "stepIndex": 1,
        "type": "condition",
        "name": "Opened the intro?",
        "subject": null,
        "bodyHtml": null,
        "bodyText": null,
        "delayDays": 2,
        "delayHours": null,
        "isActive": true,
        "sendAsReply": null,
        "quotePreviousMessages": true,
        "sentCount": 0,
        "openCount": 0,
        "clickCount": 0,
        "replyCount": 0,
        "bounceCount": 0,
        "conditionType": "email_opened",
        "conditionTrueNext": 2,
        "conditionFalseNext": 3,
        "conditionTimeoutDays": 3,
        "conditions": null
      }
    ]
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 404 not_found — Campaign not found.

Why a LinkedIn campaign is (or isn't) sending

GET /api/v1/campaigns/{id}/linkedin-throttle

Explains the current sending state of a LinkedIn or multichannel campaign: which daily or weekly allowance is holding it back, when that allowance refreshes, how many campaigns share the same LinkedIn account, and this campaign's protected share of that account's allowance versus what it has used today, per action type. `state` is a stable token — one of sending, sharing_allowance, waiting_shared_allowance, waiting_daily_allowance, waiting_weekly_allowance, resting, inmail_credits_used. `waiting: true` means a normal, expected wait rather than a failure. `status_headline` and `status_detail` are plain-language strings safe to show a person verbatim. Read-only: this endpoint cannot change a campaign or raise any limit.

• Required scope: campaigns:read

Parameters

• id — in: path — type: string — required. Campaign id (UUID).

Response — 200

{
  "data": {
    "campaign_id": "c1a2b3c4-d5e6-4789-a012-3456789abcde",
    "campaign_name": "Q3 founders — connect",
    "campaign_status": "running",
    "linkedin_account_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
    "linkedin_account_name": "Jane Doe",
    "applicable": true,
    "state": "waiting_shared_allowance",
    "status_headline": "Waiting for its share",
    "status_detail": "This campaign has used its share of today's LinkedIn allowance — the allowance is split with 2 other campaigns on this account. Yours picks up again in about 7 hours.",
    "waiting": true,
    "resumes_at": "2026-07-31T00:00:00.000Z",
    "today_allowance": {
      "used": 9,
      "allowance": 25
    },
    "account_usage_today": {
      "invites": {
        "used": 29,
        "cap": 29
      },
      "messages": {
        "used": 12,
        "cap": 100
      },
      "inmails": {
        "used": 0,
        "cap": 50,
        "creditsExhausted": false
      },
      "profile_views": {
        "used": 41,
        "cap": 100
      }
    },
    "account_warmup": {
      "account_plan": "Sales Navigator",
      "pace": "Established",
      "week": 3,
      "weeks_total": 4,
      "invites_per_week": 200
    },
    "sharing": {
      "is_shared": true,
      "campaigns_on_this_account": 3,
      "other_campaigns": [
        {
          "id": "d4e5f6a7-b8c9-4012-8345-6789abcdef01",
          "name": "EU ops leads"
        },
        {
          "id": "e5f6a7b8-c9d0-4123-8456-789abcdef012",
          "name": "Warm re-engage"
        }
      ],
      "per_action": [
        {
          "action": "Invites",
          "guaranteed_share": 9,
          "used_by_this_campaign": 9,
          "used_by_account": 29,
          "account_allowance": 29,
          "held_for_other_campaigns": 0,
          "can_send_now": false
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 404 not_found — Campaign not found.
• 422 not_linkedin_campaign — The campaign does not send on LinkedIn, so there is no LinkedIn allowance to report.

Why a campaign sent little or nothing

GET /api/v1/campaigns/{id}/skipped-actions

Returns the actions that did NOT run for this campaign in a recent window, grouped by cause. Each group carries `reason` (a stable token to branch on), a short `label`, a full plain-language `plain_english` sentence safe to show a person verbatim, `count`, `first_seen_at` / `last_seen_at`, `resumes_at` when the moment is knowable, and `is_normal_wait`. `is_normal_wait: true` marks the many causes that are the system working correctly — normal pacing that resumes on its own, not a fault. `summary_headline` answers the question in one sentence. `recent` is a capped sample of individual actions, newest first. Read-only: this endpoint cannot change a campaign or raise any limit, and it never returns raw internal error text.

• Required scope: campaigns:read

Parameters

• id — in: path — type: string — required. Campaign id (UUID).
• hours — in: query — type: integer — optional — default: 24 — range: 1–168. How far back to look, in hours. Clamped to 1–168.
• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Most individual examples to return in `recent`. Clamped to 1–100.

Response — 200

{
  "data": {
    "window_hours": 24,
    "campaign_id": "c1a2b3c4-d5e6-4789-a012-3456789abcde",
    "summary_headline": "Nothing here is broken: everything held back in the last 24 hours is waiting for one reason — today’s allowance used — and it starts again on its own.",
    "total_skipped": 41,
    "reasons": [
      {
        "reason": "daily_allowance_reached",
        "label": "Today's allowance used",
        "count": 38,
        "plain_english": "This campaign has used everything it is allowed to send today, so the rest is queued for the next day. This is normal pacing that protects your sending reputation — it starts again on its own and there is nothing to fix.",
        "first_seen_at": "2026-08-10T09:12:04.000Z",
        "last_seen_at": "2026-08-10T17:44:51.000Z",
        "is_normal_wait": true,
        "resumes_at": "2026-08-11T00:00:00.000Z"
      },
      {
        "reason": "contact_missing_details",
        "label": "Contact details missing",
        "count": 3,
        "plain_english": "Some contacts are missing the detail this step needs, such as an email address or a profile link, so those actions were skipped and the sequence moved on. Fill in the missing details and re-add those contacts if you want to reach them.",
        "first_seen_at": "2026-08-10T10:02:11.000Z",
        "last_seen_at": "2026-08-10T10:06:33.000Z",
        "is_normal_wait": false,
        "resumes_at": null
      }
    ],
    "recent": [
      {
        "occurred_at": "2026-08-10T17:44:51.000Z",
        "channel": "linkedin",
        "action": "Invites",
        "reason": "daily_allowance_reached",
        "plain_english": "This campaign has used everything it is allowed to send today, so the rest is queued for the next day. This is normal pacing that protects your sending reputation — it starts again on its own and there is nothing to fix."
      }
    ]
  }
}

Errors

• 404 not_found — Campaign not found.

Create a campaign

POST /api/v1/campaigns

Creates a campaign in draft status with one or more steps, assigned mailboxes, and (optionally) enrolled prospects. Start it later with the start endpoint. Email, LinkedIn, WhatsApp, Instagram and mixed (multichannel) campaigns are all created here; mailboxes are only required when the campaign sends email. Creating a campaign never sends anything — every message is paced later by the scheduler within that account's safe limits.

• Required scope: campaigns:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Request body

• name — type: string — required — range: 1–200. Campaign name.
• description — type: string — optional — range: –2000. Optional description.
• channel — type: string — optional — one of: email, linkedin, whatsapp, instagram, multichannel — default: email. Campaign channel. A single-channel campaign may only carry steps of that channel (plus condition steps); mix channels only under "multichannel".
• linkedinAccountId — type: string — optional — format: uuid. LinkedIn account id (for linkedin/multichannel).
• instagramAccountId — type: string — optional. Instagram account that sends this campaign. Required when the campaign carries Instagram steps. Needs an active Instagram seat.
• whatsappAccountId — type: string — optional. WhatsApp number that sends this campaign. Required when the campaign carries WhatsApp steps. Needs an active WhatsApp seat.
• timezone — type: string — optional — default: UTC — range: –100. IANA timezone for the sending schedule.
• dailySendLimit — type: integer — optional — default: 50 — range: 1–10000. Daily send cap for the campaign.
• sendingWindowStart — type: integer — optional — range: 0–23. Start hour (0–23) of the daily sending window.
• sendingWindowEnd — type: integer — optional — range: 0–23. End hour (0–23) of the daily sending window.
• scheduleDays — type: integer[] — optional. Days of week to send (0=Sun … 6=Sat).
• stopOnReply — type: boolean — optional — default: true. Stop a prospect's sequence when they reply.
• stopOnBounce — type: boolean — optional — default: true. Stop on bounce.
• stopOnUnsubscribe — type: boolean — optional — default: true. Stop on unsubscribe.
• trackOpens — type: boolean — optional — default: true. Track opens.
• trackClicks — type: boolean — optional — default: true. Track clicks.
• opt_out_style — type: string — optional — one of: link, reply — nullable. This applies to THIS campaign only — useful when one campaign writes to people in a different language from the rest of your outreach. Leave it out and the campaign keeps using your workspace setting; send null (or an empty string) to go back to following it. The choice itself works the same way it does for your workspace: How people opt out of your cold email. "link": The footer carries an Unsubscribe link — on your own verified tracking domain when you have one, otherwise on a shared WarmySender domain. "reply": The footer reads “Reply "unsubscribe" to opt out” and points back at the sending mailbox — no third-party link at all. Either way, a reply asking to unsubscribe is honored automatically and that person is never contacted again. Writing your own sentence? Put the word in quotes — like Reply “stop” — and a reply of just that word is honored too.
• opt_out_text — type: string — optional — nullable — range: –120. This applies to THIS campaign only — useful when one campaign writes to people in a different language from the rest of your outreach. Leave it out and the campaign keeps using your workspace setting; send null (or an empty string) to go back to following it. The wording rules are the same as your workspace setting: The sentence recipients click or reply to in order to opt out — written in your own words, 4–120 characters, one line. Send an empty string to go back to the default for your opt-out style ("Unsubscribe" for link, "Reply "unsubscribe" to opt out" for reply). Put {{opt_out}} inside an email or signature to place the sentence yourself.
• startDate — type: string — optional — format: date-time. Optional scheduled start.
• endDate — type: string — optional — format: date-time. Optional end date.
• steps — type: object[] — required — range: 1–50. Ordered steps. Each: { stepIndex, type (email|linkedin|instagram|whatsapp|condition), subject, bodyHtml, bodyText, delayDays, delayHours, isActive, … }. See the steps[] fields below for what an email body may contain and how to reuse a saved template. Condition steps additionally take the four condition fields below.
• steps[].subject — type: string — optional — range: –500. Subject line of an email step. Merge tags and spintax work here. Optional when the step reuses a template that carries one.
• steps[].preheader — type: string — optional — range: –200. Preview text shown after the subject line in the inbox.
• steps[].bodyHtml — type: string — optional — range: –100000. HTML email body. Use simple HTML: <p>, <br>, <strong>, <em>, <u>, <a href>, <ul>, <ol>, <li>, <h2>, <h3>, <blockquote>, <hr>, <img src>. Inline styles are supported for font-family, font-size, color, background-color, line-height, margin-left and text-align — the same formatting the WarmySender editor produces. Plain text is fine too: send bodyText (or plain body_html without tags) and line breaks are formatted automatically. Scripts and event handlers are removed. Merge tags like {{first_name | default: 'there'}} and spintax {a|b|c} work in both. Keep formatting light: plain-looking emails get more replies.
• steps[].bodyText — type: string — optional — range: –100000. Plain-text version of the email. Optional — when you send only HTML, the plain-text alternative is written for you. Merge tags like {{first_name | default: 'there'}} and spintax {a|b|c} work here too.
• steps[].templateId — type: string — optional. Reuse one of your saved email templates for this step: its subject, preview text and body are copied in. Anything you also set on the step overrides the template's version. An unknown id (or one from another workspace) fails the whole request with not_found.
• steps[].quotePreviousMessages — type: boolean — optional — default: true. Quote the earlier email underneath a threaded follow-up, the way a hand-written reply does. Default true; only applies to follow-up steps that reply in the same thread.
• steps[].instagramActionType — type: string — optional — one of: follow, view_profile, like_post, comment_post, send_dm, wait, wait_reply, condition_replied. Action for a step of type "instagram".
• steps[].instagramDmTemplate — type: string — optional. DM body for a send_dm step (supports {{firstName}} etc).
• steps[].instagramCommentTemplate — type: string — optional. Comment body for a comment_post step.
• steps[].whatsappActionType — type: string — optional — one of: send_message, wait, wait_reply, condition_replied. Action for a step of type "whatsapp". WhatsApp outreach is reply-first: send_message is the only outbound action.
• steps[].whatsappMessageTemplate — type: string — optional. Message body for a send_message step (supports {{firstName}} etc).
• steps[].conditionType — type: string — optional — one of: email_opened, email_replied, email_clicked, email_bounced, linkedin_accepted, linkedin_replied, has_linkedin_profile, timeout. Required on a step of type "condition": the signal the branch evaluates. Any other value is rejected with 400 validation_error.
• steps[].conditionTrueNext — type: integer — optional — range: -1–. Required on a condition step: stepIndex to jump to when the condition is met. Use -1 to end the sequence on the YES branch. Must point forward.
• steps[].conditionFalseNext — type: integer — optional — nullable — range: -1–. stepIndex to jump to when the condition is NOT met. Omit (or use -1) to end the sequence on the NO branch — a first-class outcome, not an error. Must point forward.
• steps[].conditionTimeoutDays — type: integer — optional — default: 3 — range: 1–30. How long the condition waits before the NO branch is taken. Defaults to 3 days when omitted.
• mailboxIds — type: string[] — required — range: –100. Mailbox ids that send this campaign.
• prospectIds — type: string[] — optional — range: –10000. Prospect ids to enroll on creation.

Request example

{
  "name": "Q3 Outbound — Founders",
  "channel": "email",
  "dailySendLimit": 50,
  "mailboxIds": [
    "5bd50e20-6b75-4429-9a5a-4a09b46e945a"
  ],
  "steps": [
    {
      "stepIndex": 0,
      "type": "email",
      "subject": "Quick question, {{firstName}}",
      "bodyHtml": "<p>Hi {{firstName}}, ...</p>",
      "delayDays": 0
    },
    {
      "stepIndex": 1,
      "type": "condition",
      "name": "Opened the intro?",
      "conditionType": "email_opened",
      "conditionTrueNext": 2,
      "conditionFalseNext": 3,
      "conditionTimeoutDays": 3,
      "delayDays": 2
    },
    {
      "stepIndex": 2,
      "type": "email",
      "subject": "Re: Quick question",
      "bodyHtml": "<p>Following up ...</p>",
      "delayDays": 3,
      "sendAsReply": true
    },
    {
      "stepIndex": 3,
      "type": "email",
      "subject": "One more idea, {{firstName}}",
      "bodyHtml": "<p>Different angle ...</p>",
      "delayDays": 3
    }
  ],
  "prospectIds": [
    "f3c4a2d1-9b7e-4c2a-8f10-2b6d5e8a1c44"
  ]
}

Response — 201

{
  "data": {
    "id": "c1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
    "name": "Q3 Outbound — Founders",
    "status": "draft",
    "channel": "email",
    "description": null,
    "timezone": "UTC",
    "dailySendLimit": 50,
    "sendingWindowStart": null,
    "sendingWindowEnd": null,
    "scheduleDays": null,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopOnUnsubscribe": true,
    "trackOpens": true,
    "trackClicks": true,
    "opt_out_style": null,
    "opt_out_text": null,
    "totalProspects": 0,
    "sent": 0,
    "opened": 0,
    "clicked": 0,
    "replied": 0,
    "bounced": 0,
    "unsubscribed": 0,
    "startDate": null,
    "endDate": null,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "updatedAt": "2026-06-10T12:00:00.000Z",
    "opt_out_effective": {
      "style": "link",
      "style_source": "workspace",
      "text": "Unsubscribe",
      "text_source": "default"
    },
    "steps": [
      {
        "id": "s1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
        "stepIndex": 0,
        "type": "email",
        "name": "Intro",
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}}, ...</p>",
        "bodyText": "Hi {{firstName}}, ...",
        "delayDays": 0,
        "delayHours": null,
        "isActive": true,
        "sendAsReply": null,
        "quotePreviousMessages": true,
        "sentCount": 0,
        "openCount": 0,
        "clickCount": 0,
        "replyCount": 0,
        "bounceCount": 0,
        "linkedinActionType": null,
        "linkedinMessageTemplate": null,
        "linkedinInviteNote": null,
        "linkedinSubject": null,
        "linkedinMaxWaitDays": null,
        "linkedinEngagementConfig": null,
        "linkedinInmailConfig": null
      }
    ]
  },
  "meta": {
    "prospects_enrolled": 1,
    "prospects_suppressed": 0,
    "mailboxes_assigned": 1
  }
}

Errors

• 400 validation_error — Body / step validation failed — including a conditionType outside the allowed list.
• 400 unsupported_field — A step supplied "conditions" (multi-condition AND/OR logic). Author those in the campaign builder; the API returns them read-only. Also returned when the opt-out setting was sent as optOutStyle / optOutText — use opt_out_style / opt_out_text, the same names your workspace settings use. Nothing was created.
• 400 campaign_step_validation_error — A step failed sequence-integrity checks (e.g. a branch pointing backward or at a step that does not exist).
• 403 subscription_blocked — Your plan doesn't allow this action.

Update a campaign

PATCH /api/v1/campaigns/{id}

Updates campaign settings. Only allowed while the campaign is in draft or paused status.

• Required scope: campaigns:write

Parameters

• id — in: path — type: string — required. Campaign id (UUID).

Request body

• name — type: string — optional — range: 1–200. Campaign name.
• description — type: string — optional — range: –2000. Description.
• dailySendLimit — type: integer — optional — range: 1–10000. Daily send cap.
• sendingWindowStart — type: integer — optional — range: 0–23. Window start hour.
• sendingWindowEnd — type: integer — optional — range: 0–23. Window end hour.
• scheduleDays — type: integer[] — optional. Days of week (0–6).
• stopOnReply — type: boolean — optional. Stop on reply.
• stopOnBounce — type: boolean — optional. Stop on bounce.
• stopOnUnsubscribe — type: boolean — optional. Stop on unsubscribe.
• trackOpens — type: boolean — optional. Track opens.
• trackClicks — type: boolean — optional. Track clicks.
• opt_out_style — type: string — optional — one of: link, reply — nullable. This applies to THIS campaign only — useful when one campaign writes to people in a different language from the rest of your outreach. Leave it out and the campaign keeps using your workspace setting; send null (or an empty string) to go back to following it. The choice itself works the same way it does for your workspace: How people opt out of your cold email. "link": The footer carries an Unsubscribe link — on your own verified tracking domain when you have one, otherwise on a shared WarmySender domain. "reply": The footer reads “Reply "unsubscribe" to opt out” and points back at the sending mailbox — no third-party link at all. Either way, a reply asking to unsubscribe is honored automatically and that person is never contacted again. Writing your own sentence? Put the word in quotes — like Reply “stop” — and a reply of just that word is honored too.
• opt_out_text — type: string — optional — nullable — range: –120. This applies to THIS campaign only — useful when one campaign writes to people in a different language from the rest of your outreach. Leave it out and the campaign keeps using your workspace setting; send null (or an empty string) to go back to following it. The wording rules are the same as your workspace setting: The sentence recipients click or reply to in order to opt out — written in your own words, 4–120 characters, one line. Send an empty string to go back to the default for your opt-out style ("Unsubscribe" for link, "Reply "unsubscribe" to opt out" for reply). Put {{opt_out}} inside an email or signature to place the sentence yourself.
• startDate — type: string — optional — format: date-time — nullable. Scheduled start, or null.
• endDate — type: string — optional — format: date-time — nullable. End date, or null.

Request example

{
  "dailySendLimit": 80,
  "scheduleDays": [
    1,
    2,
    3,
    4,
    5
  ]
}

Response — 200

{
  "data": {
    "id": "c1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
    "name": "Q3 Outbound — Founders",
    "status": "draft",
    "channel": "email",
    "description": null,
    "timezone": "UTC",
    "dailySendLimit": 80,
    "sendingWindowStart": null,
    "sendingWindowEnd": null,
    "scheduleDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopOnUnsubscribe": true,
    "trackOpens": true,
    "trackClicks": true,
    "opt_out_style": null,
    "opt_out_text": null,
    "totalProspects": 0,
    "sent": 0,
    "opened": 0,
    "clicked": 0,
    "replied": 0,
    "bounced": 0,
    "unsubscribed": 0,
    "startDate": null,
    "endDate": null,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "updatedAt": "2026-06-10T12:00:00.000Z",
    "opt_out_effective": {
      "style": "link",
      "style_source": "workspace",
      "text": "Unsubscribe",
      "text_source": "default"
    },
    "steps": [
      {
        "id": "s1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
        "stepIndex": 0,
        "type": "email",
        "name": "Intro",
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}}, ...</p>",
        "bodyText": "Hi {{firstName}}, ...",
        "delayDays": 0,
        "delayHours": null,
        "isActive": true,
        "sendAsReply": null,
        "quotePreviousMessages": true,
        "sentCount": 0,
        "openCount": 0,
        "clickCount": 0,
        "replyCount": 0,
        "bounceCount": 0,
        "linkedinActionType": null,
        "linkedinMessageTemplate": null,
        "linkedinInviteNote": null,
        "linkedinSubject": null,
        "linkedinMaxWaitDays": null,
        "linkedinEngagementConfig": null,
        "linkedinInmailConfig": null
      }
    ]
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

• The create, read and update responses carry opt_out_effective: the opt-out this campaign will actually print, after the per-campaign override falls back to your workspace setting field by field. style_source and text_source say which of the two each half came from.
• Custom wording changes what the opt-out says, never whether one appears — every cold email carries one.

Errors

• 400 invalid_status — Campaign isn't in draft/paused status.
• 400 validation_error — opt_out_text was too short, too long, or worded in a way that would not read as an opt-out.
• 400 unsupported_field — The opt-out setting was sent as optOutStyle / optOutText. Use opt_out_style / opt_out_text — the same names your workspace settings use. Nothing was changed.
• 404 not_found — Campaign not found.

Start a campaign

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

Moves a draft/paused campaign into running (or scheduled, when startDate is in the future). No request body. Before starting, the campaign runs the same configuration check as the Launch button in the app — sequences that would strand prospects mid-flow are rejected with 400 campaign_validation_failed and the offending steps listed.

• Required scope: campaigns:write

Parameters

• id — in: path — type: string — required. Campaign id (UUID).
• force — in: query — type: string — optional — one of: 1, true. Launch even though the configuration check found problems — the headless equivalent of "Launch anyway" in the app. Omit unless you have reviewed the reported violations.

Response — 200

{
  "data": {
    "id": "c1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
    "name": "Q3 Outbound — Founders",
    "status": "running",
    "channel": "email",
    "description": null,
    "timezone": "UTC",
    "dailySendLimit": 50,
    "sendingWindowStart": null,
    "sendingWindowEnd": null,
    "scheduleDays": null,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopOnUnsubscribe": true,
    "trackOpens": true,
    "trackClicks": true,
    "opt_out_style": null,
    "opt_out_text": null,
    "totalProspects": 0,
    "sent": 0,
    "opened": 0,
    "clicked": 0,
    "replied": 0,
    "bounced": 0,
    "unsubscribed": 0,
    "startDate": null,
    "endDate": null,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "updatedAt": "2026-06-10T12:00:00.000Z",
    "steps": [
      {
        "id": "s1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
        "stepIndex": 0,
        "type": "email",
        "name": "Intro",
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}}, ...</p>",
        "bodyText": "Hi {{firstName}}, ...",
        "delayDays": 0,
        "delayHours": null,
        "isActive": true,
        "sendAsReply": null,
        "quotePreviousMessages": true,
        "sentCount": 0,
        "openCount": 0,
        "clickCount": 0,
        "replyCount": 0,
        "bounceCount": 0,
        "linkedinActionType": null,
        "linkedinMessageTemplate": null,
        "linkedinInviteNote": null,
        "linkedinSubject": null,
        "linkedinMaxWaitDays": null,
        "linkedinEngagementConfig": null,
        "linkedinInmailConfig": null
      }
    ]
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 400 invalid_status — Campaign can't be started from its current status.
• 400 campaign_validation_failed — The sequence has configuration problems that would strand prospects. details.violations lists each one with its step index and a fix hint. Resolve them, or retry with ?force=1. Note that not every violation is force-overridable — see no_active_steps below.
• 400 no_active_steps — Every step in the campaign is switched off, so it could never send anything. Switch at least one step back on, then start it again. This one is NOT overridable with ?force=1 — forcing it would only start a campaign that cannot send.
• 403 subscription_blocked — Your plan doesn't allow this action.
• 403 insufficient_scope — The campaign runs Instagram or WhatsApp steps and this key lacks that channel's write permission. Nothing was started.
• 403 seat_required — The campaign runs Instagram or WhatsApp steps and the workspace has no active seat for that channel.
• 422 account_not_connected — The Instagram account or WhatsApp number this campaign sends from is not connected. Reconnect it, then start again.
• 429 rate_limited — Too many Instagram/WhatsApp campaign changes in one minute. Nothing was changed — wait for the Retry-After delay.
• 404 not_found — Campaign not found.

Pause a campaign

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

Pauses a running campaign. No request body. Pausing is never blocked by seats or by a disconnected sender — stopping your own outreach always works.

• Required scope: campaigns:write

Parameters

• id — in: path — type: string — required. Campaign id (UUID).

Response — 200

{
  "data": {
    "id": "c1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
    "name": "Q3 Outbound — Founders",
    "status": "paused",
    "channel": "email",
    "description": null,
    "timezone": "UTC",
    "dailySendLimit": 50,
    "sendingWindowStart": null,
    "sendingWindowEnd": null,
    "scheduleDays": null,
    "stopOnReply": true,
    "stopOnBounce": true,
    "stopOnUnsubscribe": true,
    "trackOpens": true,
    "trackClicks": true,
    "opt_out_style": null,
    "opt_out_text": null,
    "totalProspects": 0,
    "sent": 0,
    "opened": 0,
    "clicked": 0,
    "replied": 0,
    "bounced": 0,
    "unsubscribed": 0,
    "startDate": null,
    "endDate": null,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "updatedAt": "2026-06-10T12:00:00.000Z",
    "steps": [
      {
        "id": "s1a2b3c4-d5e6-47f8-9a0b-1c2d3e4f5a6b",
        "stepIndex": 0,
        "type": "email",
        "name": "Intro",
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}}, ...</p>",
        "bodyText": "Hi {{firstName}}, ...",
        "delayDays": 0,
        "delayHours": null,
        "isActive": true,
        "sendAsReply": null,
        "quotePreviousMessages": true,
        "sentCount": 0,
        "openCount": 0,
        "clickCount": 0,
        "replyCount": 0,
        "bounceCount": 0,
        "linkedinActionType": null,
        "linkedinMessageTemplate": null,
        "linkedinInviteNote": null,
        "linkedinSubject": null,
        "linkedinMaxWaitDays": null,
        "linkedinEngagementConfig": null,
        "linkedinInmailConfig": null
      }
    ]
  },
  "meta": {
    "request_id": "req_mq28denhy91fh6"
  }
}

Errors

• 400 invalid_status — Campaign isn't running.
• 403 insufficient_scope — The campaign runs Instagram or WhatsApp steps and this key lacks that channel's write permission.
• 404 not_found — Campaign not found.

Enroll prospects

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

Adds prospects to a campaign by prospect id, audience list id, email, and/or WhatsApp number. Suppressed prospects are skipped and counted separately. Provide at least one of prospectIds, listIds, emails, whatsappPhones. Emails and numbers that match no existing lead are reported back rather than silently dropped.

• Required scope: enrollments:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Parameters

• id — in: path — type: string — required. Campaign id (UUID).

Request body

• prospectIds — type: string[] — optional. Prospect ids to enroll.
• listIds — type: string[] — optional. Audience list ids — every prospect on each list is enrolled.
• emails — type: string[] — optional. Prospect emails to enroll.
• whatsappPhones — type: string[] — optional. WhatsApp numbers of existing leads to enroll. Any human format is accepted (+49 171 234 5678, 0049…, bare digits, a wa.me link) and normalized before matching.

Request example

{
  "emails": [
    "[email protected]"
  ],
  "listIds": [
    "list_9f3a2b"
  ],
  "whatsappPhones": [
    "+49 171 2345678"
  ]
}

Response — 200

{
  "data": {
    "enrolledCount": 12,
    "suppressedCount": 1,
    "invalidCount": 0,
    "alreadyEnrolledCount": 2,
    "totalProcessed": 15,
    "notFoundEmails": [],
    "notFoundPhones": []
  }
}

Errors

• 400 validation_error — No targets given or body invalid.
• 403 insufficient_scope — The campaign runs Instagram or WhatsApp steps and this key lacks that channel's write permission. Nobody was enrolled.
• 403 seat_required — The campaign runs Instagram or WhatsApp steps and the workspace has no active seat for that channel.
• 404 not_found — Campaign not found.

Unenroll prospects

DELETE /api/v1/campaigns/{id}/enrollments

Removes prospects from a campaign (soft-stop — their audit history is preserved and any pending sends are cancelled). Provide at least one of prospectIds, emails.

• Required scope: enrollments:write

Parameters

• id — in: path — type: string — required. Campaign id (UUID).

Request body

• prospectIds — type: string[] — optional. Prospect ids to unenroll.
• emails — type: string[] — optional. Prospect emails to unenroll.

Request example

{
  "emails": [
    "[email protected]"
  ]
}

Response — 200

{
  "data": {
    "unenrolledCount": 1,
    "totalProcessed": 1
  }
}

Errors

• 400 validation_error — No targets given or body invalid.
• 404 not_found — Campaign not found.

List webhooks

GET /api/v1/webhooks

Returns your configured webhook endpoints (without secrets).

• Required scope: webhooks:read

Response — 200

{
  "data": [
    {
      "id": "wh_2c1a9f",
      "url": "https://example.com/hooks/warmysender",
      "events": [
        "reply.received",
        "email.bounced"
      ],
      "isActive": true,
      "lastTriggeredAt": null,
      "failureCount": 0,
      "createdAt": "2026-06-10T12:00:00.000Z",
      "updatedAt": "2026-06-10T12:00:00.000Z"
    }
  ]
}

Create a webhook

POST /api/v1/webhooks

Registers a webhook endpoint for one or more event types. The signing secret (whsec_…) is returned ONCE in this response — store it; you'll use it to verify payload signatures.

• Required scope: webhooks:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Request body

• url — type: string — required — format: uri — range: –500. HTTPS URL that receives POST deliveries.
• events — type: string[] — required — range: 1–. Event types to subscribe to (see Webhook Events).

Request example

{
  "url": "https://example.com/hooks/warmysender",
  "events": [
    "reply.received",
    "email.bounced",
    "linkedin.reply_received"
  ]
}

Response — 201

{
  "data": {
    "id": "wh_2c1a9f",
    "url": "https://example.com/hooks/warmysender",
    "events": [
      "reply.received",
      "email.bounced",
      "linkedin.reply_received"
    ],
    "isActive": true,
    "secret": "whsec_3f9a...redacted",
    "createdAt": "2026-06-10T12:00:00.000Z"
  },
  "message": "Webhook created. Save the secret - it will not be shown again."
}

Errors

• 400 validation_error — Invalid URL or unknown event type.

Update a webhook

PATCH /api/v1/webhooks/{id}

Change a webhook's URL, subscribed events, or active flag.

• Required scope: webhooks:write

Parameters

• id — in: path — type: string — required. Webhook id.

Request body

• url — type: string — optional — format: uri — range: –500. New delivery URL.
• events — type: string[] — optional — range: 1–. Replacement list of event types.
• isActive — type: boolean — optional. Enable or disable deliveries.

Request example

{
  "isActive": false
}

Response — 200

{
  "data": {
    "id": "wh_2c1a9f",
    "url": "https://example.com/hooks/warmysender",
    "events": [
      "reply.received"
    ],
    "isActive": false,
    "lastTriggeredAt": null,
    "failureCount": 0,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "updatedAt": "2026-06-10T12:05:00.000Z"
  }
}

Errors

• 400 validation_error — Body failed validation.
• 404 not_found — Webhook not found.

Delete a webhook

DELETE /api/v1/webhooks/{id}

Permanently removes a webhook endpoint. Returns 204 with no body.

• Required scope: webhooks:write

Parameters

• id — in: path — type: string — required. Webhook id.

Response — 204

No response body.

Errors

• 404 not_found — Webhook not found.

Send a test event

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

Queues a webhook.test delivery to the endpoint so you can verify signature handling end-to-end. No request body.

• Required scope: webhooks:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Parameters

• id — in: path — type: string — required. Webhook id.

Response — 200

{
  "data": {
    "eventId": "evt_a1b2c3",
    "status": "queued",
    "message": "Test webhook event has been queued for delivery"
  }
}

Errors

• 404 not_found — Webhook not found.

List LinkedIn accounts

GET /api/v1/linkedin/accounts

Returns connected LinkedIn accounts with their daily engagement limits and how many actions remain today.

• Required scope: linkedin:read

Parameters

• limit — in: query — type: integer — optional — default: 50 — range: 1–100. Results to return (1–100).

Response — 200

{
  "data": [
    {
      "id": "li_5a2b1c",
      "name": "Jordan Lee",
      "linkedin_url": "https://www.linkedin.com/in/jordanlee",
      "status": "connected",
      "linkedin_account_type": "classic",
      "strategy": "steady",
      "ramp_week": 3,
      "engagements_today": 4,
      "engagements_day": "2026-06-10",
      "created_at": "2026-05-20T10:00:00.000Z",
      "daily_limits": {
        "engagements_per_day": 30,
        "engagements_remaining": 26
      }
    }
  ]
}

React to a post

POST /api/v1/linkedin/posts/{postId}/reactions

Adds a reaction (like, celebrate, etc.) to a LinkedIn post from one of your connected accounts. Subject to per-account daily engagement limits — account safety always wins.

• Required scope: linkedin:write
• Idempotency-Key required — send a unique key so retries never duplicate.

Parameters

• postId — in: path — type: string — required. LinkedIn post id (URN).

Request body

• linkedin_account_id — type: string — required. Which connected LinkedIn account reacts.
• reaction_type — type: string — optional — one of: LIKE, CELEBRATE, SUPPORT, LOVE, INSIGHTFUL, FUNNY — default: LIKE. Reaction (case-insensitive; defaults to LIKE).

Request example

{
  "linkedin_account_id": "li_5a2b1c",
  "reaction_type": "LIKE"
}

Response — 201

{
  "data": {
    "post_id": "urn:li:activity:7300000000000000000",
    "reaction_type": "LIKE",
    "linkedin_account_id": "li_5a2b1c"
  }
}

Errors

• 400 account_not_connected — The LinkedIn account isn't connected.
• 401 account_unauthorized — The LinkedIn session needs re-authentication.
• 429 daily_limit_reached — The account hit its daily engagement limit.

List reactions on a post

GET /api/v1/linkedin/posts/{postId}/reactions

Lists who reacted to a post, as seen by one of your connected accounts. Cursor paginated.

• Required scope: linkedin:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• postId — in: path — type: string — required. LinkedIn post id (URN).
• linkedin_account_id — in: query — type: string — required. Which connected account performs the read.
• limit — in: query — type: integer — optional — default: 20 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.

Response — 200

{
  "data": [
    {
      "user_id": "urn:li:person:abc",
      "name": "Sam Rivera",
      "reaction_type": "LIKE",
      "timestamp": "2026-06-10T11:00:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Errors

• 400 account_not_connected — The LinkedIn account isn't connected.
• 401 account_unauthorized — The LinkedIn session needs re-authentication.

Verify one email address

POST /api/v1/verification/verify

Checks a single address and returns one of four outcomes with a plain-English reason. Note that a confirmed mailbox is only one of them — on a mail server that accepts every address the outcome is `risky`, which is deliverable-but-unconfirmable rather than bad. Answers we cannot confirm are always free.

• Required scope: verification:write

Request body

• email — type: string — required — format: email. The address to check.

Request example

{
  "email": "[email protected]"
}

Response — 200

{
  "data": {
    "email": "[email protected]",
    "status": "valid",
    "reason": "The mail provider accepted this address.",
    "is_catch_all": false,
    "mx_host": "aspmx.l.google.com"
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• Accepts an optional `Idempotency-Key` header so a retry never spends a second credit.
• Results are one of `valid`, `invalid`, `risky` or `unknown`. `risky` means the domain accepts every address, so delivery cannot be confirmed. `unknown` means no definitive answer — never charged.

Errors

• 402 verifier_access_required — Paying unblocks it: there is no plan on the account, or an invoice is unsettled, or the one free daily check is already used. Verification credits clear all three immediately and need no subscription — `details.reason` says which one it is.
• 403 verifier_access_required — The plan on this account carries no monthly verification allowance (or the account is on hold). Credits still work without a plan — `details.can_buy_credits` says whether they can be bought.
• 429 verification_rate_limited — More than 20 single checks in a minute for this workspace.
• 429 allowance_exhausted — The plan allowance is used up and there are no credits to cover the check. Nothing was charged.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.
• 503 verification_capacity_reserved — Checking capacity is reserved for paid work right now. Nothing was used up — a free check is given back — so retry shortly.
• 503 verification_unavailable — Checking is temporarily unavailable. Nothing was charged.

Start a verification run

POST /api/v1/verification/batches

Submits a list of addresses to be checked in the background and returns a run id to poll. Pass either an `emails` array or a `list_id` to check one of your prospect lists in place. A run starts in full or not at all: if the list is larger than what your allowance and credits cover today, the whole request is refused with `exceeds_today` and nothing is charged — the error says how many can start today, so split the list to that size or add credits.

• Required scope: verification:write

Request body

• emails — type: string[] — optional — range: 1–5000. Addresses to check (1–5,000). Duplicates are collapsed. Provide this OR list_id, not both.
• list_id — type: string — optional. Check every address in one of your prospect lists instead of listing them out. Contacts sourced from LinkedIn that have no real email address yet are skipped and never charged for — the response reports how many under `skipped_without_email`. Provide this OR emails, not both.
• name — type: string — optional. Label for this run. Defaults to an auto-generated one.

Request example

{
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "name": "Q3 outbound list"
}

Response — 202

{
  "data": {
    "id": "b1a2c3d4-...",
    "status": "processing",
    "accepted": 2,
    "submitted": 2
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• Accepts an optional `Idempotency-Key` header so a retry never starts a second run.
• `accepted` always equals `submitted` — a run is admitted in full or refused in full. A list too big for today comes back as a 429 `exceeds_today` carrying `details.admissible_today`; nothing is charged and nothing is created.
• At most 5,000 addresses per run, and at most 5 runs started per minute.
• With `list_id`, contacts that have no real email address yet (LinkedIn-sourced) are left out before anything is charged; `skipped_without_email` in the response says how many.

Errors

• 400 batch_too_large — More than 5,000 addresses were submitted in one run — including when a `list_id` resolves to more than that.
• 402 verifier_access_required — Paying unblocks it: there is no plan on the account, or an invoice is unsettled, or the one free daily check is already used. Verification credits clear all three immediately and need no subscription — `details.reason` says which one it is.
• 403 verifier_access_required — The plan on this account carries no monthly verification allowance (or the account is on hold). Credits still work without a plan — `details.can_buy_credits` says whether they can be bought.
• 404 not_found — A `list_id` was given but no such prospect list exists in this workspace.
• 422 no_verifiable_emails — The list exists but holds no address we can check — usually because every contact came from LinkedIn and has no real email address yet.
• 429 verification_rate_limited — More than 5 runs started in a minute for this workspace.
• 429 allowance_exhausted — The allowance and credit balance cover none of the list. Nothing was charged.
• 429 exceeds_today — The list is larger than everything this workspace can check today (allowance left plus usable credits). Nothing was charged and no run was created — `details.admissible_today` says how many would start now.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

List verification runs

GET /api/v1/verification/batches

Lists this workspace's verification runs, newest first, with their progress and result counts.

• Required scope: verification:read
• Returns a cursor-paginated list — follow pagination.next_cursor.

Parameters

• limit — in: query — type: integer — optional — default: 25 — range: 1–100. Results per page (1–100).
• cursor — in: query — type: string — optional. next_cursor from the previous page.

Response — 200

{
  "data": [
    {
      "id": "b1a2c3d4-...",
      "name": "Q3 outbound list",
      "status": "completed",
      "source": "upload",
      "total": 2,
      "checked": 2,
      "valid": 1,
      "invalid": 1,
      "risky": 0,
      "unknown": 0,
      "created_at": "2026-07-29T09:00:00.000Z",
      "started_at": "2026-07-29T09:00:01.000Z",
      "completed_at": "2026-07-29T09:04:12.000Z"
    }
  ],
  "pagination": {
    "has_more": false
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• Reading costs nothing against your verification allowance.

Errors

• 403 verifier_access_required — This account is on hold, so its verification data cannot be read.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

Get a verification run

GET /api/v1/verification/batches/{id}

Returns the progress and result counts for one verification run.

• Required scope: verification:read

Parameters

• id — in: path — type: string — required. The run id.

Response — 200

{
  "data": {
    "id": "b1a2c3d4-...",
    "name": "Q3 outbound list",
    "status": "processing",
    "source": "upload",
    "total": 2000,
    "checked": 640,
    "valid": 512,
    "invalid": 96,
    "risky": 24,
    "unknown": 8,
    "created_at": "2026-07-29T09:00:00.000Z",
    "started_at": "2026-07-29T09:00:01.000Z",
    "completed_at": null
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

Errors

• 404 not_found — No run with that id in this workspace.
• 403 verifier_access_required — This account is on hold, so its verification data cannot be read.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

Get per-address results

GET /api/v1/verification/batches/{id}/results

Returns the outcome for each address in a run, optionally filtered to one outcome. Results are available while the run is still going, so you can act on the part that has finished.

• Required scope: verification:read

Parameters

• id — in: path — type: string — required. The run id.
• status — in: query — type: string — optional — one of: pending, processing, valid, invalid, risky, unknown, error, cancelled. Return only addresses with this outcome. Omit for all.
• limit — in: query — type: integer — optional — default: 100 — range: 1–1000. Results per page (1–1,000).
• offset — in: query — type: integer — optional — default: 0 — range: 0–. Result offset for paging.

Response — 200

{
  "data": [
    {
      "email": "[email protected]",
      "status": "valid",
      "reason": "The mail provider accepted this address.",
      "is_catch_all": false,
      "mx_host": "aspmx.l.google.com",
      "checked_at": "2026-07-29T09:01:44.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "total": 1,
    "limit": 100,
    "offset": 0
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• The run summary travels with every page, so polling takes one request rather than two.
• Each result carries a plain-English `reason`. Addresses not yet reached read as `pending` or `processing`.

Errors

• 400 validation_error — The `status` filter is not one of the listed outcomes.
• 404 not_found — No run with that id in this workspace.
• 403 verifier_access_required — This account is on hold, so its verification data cannot be read.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

Stop a run and refund unused credits

POST /api/v1/verification/batches/{id}/cancel

Stops a verification run that is still going and returns the credits that were paid for but never used. Addresses already checked keep their results.

• Required scope: verification:write

Parameters

• id — in: path — type: string — required. The run id.

Response — 200

{
  "data": {
    "id": "b1a2c3d4-...",
    "status": "cancelled",
    "cancelled": true,
    "stopped_addresses": 1360,
    "credits_refunded": 1360,
    "credit_balance": 4360
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• Safe to call more than once. Only the first call stops the run and refunds; later calls return `cancelled: false` with `credits_refunded: 0` rather than an error, so a retry can never refund twice.
• Calling this on a run that already finished is not an error — it reports the run's current state.

Errors

• 404 not_found — No run with that id in this workspace.
• 403 verifier_access_required — This account is on hold, so its verification data cannot be read.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

Build a prospect list from results

POST /api/v1/verification/batches/{id}/create-list

Builds a reusable prospect list from a finished run. By default it keeps two kinds of address: ones whose mailbox was confirmed, and ones on a mail server that accepts every address. Pass keep=valid for confirmed-only, or keep=risky for catch-all only. The default mix is on purpose — many catch-all addresses still deliver — and the response reports the split so you can decide how to send.

• Required scope: verification:write

Parameters

• id — in: path — type: string — required. The run id.

Request body

• keep — type: string — optional — one of: campaign_ready, valid, risky — default: campaign_ready. Who to put in the list. campaign_ready (default) = confirmed plus catch-all. valid = confirmed only. risky = catch-all only.

Request example

{
  "keep": "valid"
}

Response — 201

{
  "data": {
    "created": true,
    "list_id": "l9f8e7d6-...",
    "list_name": "Q3 outbound list (verified) — confirmed only",
    "address_count": 604,
    "confirmed_count": 604,
    "unconfirmable_count": 0,
    "keep": "valid"
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• `keep` omitted is the same as `campaign_ready` (confirmed plus catch-all). `keep=valid` builds a separate confirmed-only list so it cannot collide with the default list.
• `confirmed_count` is the mailboxes confirmed to exist. `unconfirmable_count` is the ones on a mail server that accepts every address — send to those gradually, with warmup running.
• `address_count` is how many contacts ended up in the list after duplicates were collapsed, so it can differ slightly from the two counts added together.
• The default list is named after your original run with "- Verified" on the end. Confirmed-only lists add "confirmed only". That is a label, not a promise about every address in it — read the two counts above for what is actually confirmed.
• Calling it twice with the same keep returns the same list rather than creating a duplicate.
• Costs nothing — the addresses were already checked when the run happened.
• If the run produced nothing usable, the response is 200 with `created: false` rather than an error.

Errors

• 400 invalid_keep — keep was not campaign_ready, valid, or risky.
• 404 not_found — No run with that id in this workspace.
• 409 batch_not_finished — The run is still going, or it did not finish successfully.
• 403 verifier_access_required — This account is on hold, so its verification data cannot be read.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

Check remaining verification allowance

GET /api/v1/verification/allowance

Returns whether this account can check an address right now and what would pay for it — the plan allowance left this month and today, the purchased credit balance, free checks left today, and the largest run accepted. Read this before submitting so you never discover a limit by being refused.

• Required scope: verification:read

Response — 200

{
  "data": {
    "can_verify_now": true,
    "access_source": "plan",
    "monthly_allowance": 10000,
    "monthly_used": 1240,
    "monthly_remaining": 8760,
    "daily_allowance": 333,
    "daily_used": 40,
    "daily_remaining": 293,
    "credit_balance": 5000,
    "free_checks_remaining_today": 0,
    "can_buy_credits": true,
    "verifiable_now": 5293,
    "max_addresses_per_batch": 5000
  },
  "meta": {
    "request_id": "req_lz3k9a2b"
  }
}

• `can_verify_now` is the field to branch on: true means a check would be admitted this instant, whatever is funding it.
• `access_source` says what would pay for it — `plan` (monthly allowance), `credits` (purchased, no subscription needed), `free_daily` (the one free check per day), or `none`.
• `verifiable_now` counts plan allowance plus credit headroom ONLY. It reads 0 for an account running on its free daily check, so do not read it as "no access" — check `can_verify_now` and `free_checks_remaining_today` first.
• Purchased credits never expire, need no subscription, and are only ever spent on a confirmed result.

Errors

• 403 verifier_access_required — This account is on hold, so its verification data cannot be read.
• 503 verifier_access_required — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

reply.received

A prospect replied (email or LinkedIn).

{
  "prospectId": "f3c4a2d1-...",
  "prospectEmail": "[email protected]",
  "campaignId": "c1a2b3c4-...",
  "mailboxId": "5bd50e20-...",
  "subject": "Re: Quick question",
  "messageId": "<...>",
  "receivedAt": "2026-06-10T11:00:00.000Z",
  "channel": "email"
}

email.bounced

An outbound email bounced (hard or soft).

{
  "prospectEmail": "[email protected]",
  "campaignId": "c1a2b3c4-...",
  "mailboxId": "5bd50e20-...",
  "bounceType": "hard",
  "bounceReason": "550 user unknown",
  "bouncedAt": "2026-06-10T11:01:00.000Z"
}

email.unsubscribed

A prospect unsubscribed.

{
  "prospectId": "f3c4a2d1-...",
  "prospectEmail": "[email protected]",
  "campaignId": "c1a2b3c4-...",
  "unsubscribedAt": "2026-06-10T11:02:00.000Z"
}

email.opened

A tracked email was opened.

{
  "prospectId": "f3c4a2d1-...",
  "prospectEmail": "[email protected]",
  "campaignId": "c1a2b3c4-...",
  "stepIndex": 0,
  "openedAt": "2026-06-10T11:03:00.000Z"
}

email.clicked

A tracked link was clicked.

{
  "prospectId": "f3c4a2d1-...",
  "prospectEmail": "[email protected]",
  "campaignId": "c1a2b3c4-...",
  "url": "https://yourdomain.com/demo",
  "clickedAt": "2026-06-10T11:04:00.000Z"
}

prospect.suppressed

A prospect was added to the suppression list.

{
  "prospectId": "f3c4a2d1-...",
  "email": "[email protected]",
  "reason": "manual opt-out",
  "suppressedAt": "2026-06-10T11:05:00.000Z"
}

limit.hit

A sending limit (mailbox/domain/prospect/cooldown) was reached.

{
  "limitType": "daily_mailbox",
  "mailboxId": "5bd50e20-...",
  "currentValue": 50,
  "limitValue": 50,
  "hitAt": "2026-06-10T11:06:00.000Z"
}

linkedin.invite_accepted

A LinkedIn connection invite was accepted.

{
  "prospectName": "Sam Rivera",
  "prospectLinkedinUrl": "https://www.linkedin.com/in/samrivera",
  "campaignId": "c1a2b3c4-...",
  "enrollmentId": "enr_...",
  "linkedinAccountId": "li_5a2b1c",
  "acceptedAt": "2026-06-10T11:07:00.000Z"
}

linkedin.reply_received

A LinkedIn message reply was received.

{
  "prospectName": "Sam Rivera",
  "prospectLinkedinUrl": "https://www.linkedin.com/in/samrivera",
  "campaignId": "c1a2b3c4-...",
  "enrollmentId": "enr_...",
  "linkedinAccountId": "li_5a2b1c",
  "messageText": "Sure, let's talk",
  "threadId": "th_...",
  "receivedAt": "2026-06-10T11:08:00.000Z"
}

instagram.reply_received

An Instagram DM reply was received.

{
  "prospectName": "Sam Rivera",
  "instagramProfileUrl": "https://instagram.com/samrivera",
  "instagramUsername": "samrivera",
  "campaignId": "c1a2b3c4-...",
  "enrollmentId": "enr_...",
  "instagramAccountId": "ig_5a2b1c",
  "messageText": "Sure, send it over",
  "threadId": "th_...",
  "receivedAt": "2026-06-10T11:08:30.000Z"
}

whatsapp.reply_received

A WhatsApp reply was received.

{
  "prospectName": "Sam Rivera",
  "whatsappPhone": "491712345678",
  "campaignId": "c1a2b3c4-...",
  "enrollmentId": "enr_...",
  "whatsappAccountId": "wa_5a2b1c",
  "messageText": "Yes, go ahead",
  "chatId": "ch_...",
  "receivedAt": "2026-06-10T11:08:45.000Z"
}

webhook.test

A manual test event sent from the test endpoint.

{
  "webhookId": "wh_2c1a9f",
  "timestamp": "2026-06-10T11:09:00.000Z",
  "message": "This is a test event from WarmySender"
}