Sequencer API

• check_circleMethod: Bearer API key (Authorization: Bearer <api_key>) or X-Api-Key.
• check_circlePermission: sequencer on the API key.
• check_circlePlan: sequencer_enabled must be true on the tenant's active plan.

Common errors:

{ "status": "error", "reason": "Your current plan does not include the Email Sequencer." }

{ "status": "error", "reason": "API key does not have sequencer permission." }

All routes are prefixed with /api/v1/sequencer and throttled via api-v1-sequencer (60 requests/min per API key).

GET /api/v1/sequencer/leads

List leads with cursor pagination.

Query parameters: status, list_id, tag, saved_filter_id, since, q, cursor.

curl "$APP_URL/api/v1/sequencer/leads?q=acme" \
  -H "Authorization: Bearer $API_KEY"

POST /api/v1/sequencer/leads

Create or update a single lead by email.

Required: email. Optional: first_name, last_name, company, title, phone, timezone, source, custom_fields.

curl -X POST "$APP_URL/api/v1/sequencer/leads" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"lead@example.com","first_name":"Alex"}'

POST /api/v1/sequencer/leads/webhook

Webhook-style lead ingestion with optional tags[] and list_id.

POST /api/v1/sequencer/leads/import

Bulk import via multipart file, raw csv string, or leads[] array (provide one).

• check_circlefile: multipart upload (csv/txt/xlsx/xls, max 10 MB). Example: curl -F "file=@leads.csv" -H "Authorization: Bearer $API_KEY" ...
• check_circlecsv: raw CSV string in JSON (max 10 KB). First row = headers; email column required.
• check_circleleads: array of objects (max 1000), each with email.
• check_circleUnknown CSV columns map to custom_fields.
• check_circle≤50 rows: synchronous 201 with counts.
• check_circle>50 rows: 202 with task_id; poll GET /api/v1/sequencer/leads/import/{task}.

GET/PATCH/DELETE /api/v1/sequencer/leads/{lead}

Standard CRUD for individual leads.

Lead tags — /api/v1/sequencer/lead-tags

curl -X POST "$APP_URL/api/v1/sequencer/lead-tags" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"hot","color":"#ff5500"}'

Lead lists — /api/v1/sequencer/lead-lists

curl -X POST "$APP_URL/api/v1/sequencer/lead-lists" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q1 prospects","lead_ids":[1,2,3]}'

Lead notes — /api/v1/sequencer/lead-notes

curl -X POST "$APP_URL/api/v1/sequencer/lead-notes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lead_id":1,"body":"Called — interested in demo"}'

Saved filters — /api/v1/sequencer/saved-filters

Reusable filter definitions for the leads index (status, q, tag, list_id).

curl -X POST "$APP_URL/api/v1/sequencer/saved-filters" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Active hot leads","filters":{"status":"active","tag":"hot"}}'

Full CRUD: GET, POST, GET/{id}, PATCH/{id}, DELETE/{id}.

GET/POST /api/v1/sequencer/sequences

List or create sequences. Steps can be nested on create/update.

PUT /api/v1/sequencer/sequences/{sequence}/steps

Sync all steps in one request. Step types: email, follow_up, wait, condition.

curl -X PUT "$APP_URL/api/v1/sequencer/sequences/1/steps" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {"type":"email","position":1,"subject":"Hello","body":"Hi there"},
      {"type":"wait","position":2,"wait_days":2}
    ]
  }'

DELETE /api/v1/sequencer/sequences/{sequence}/steps/{step}

Remove a single step without replacing the full list.

GET /api/v1/sequencer/campaigns

List campaigns. Query: status, q, sort, dir, per_page.

POST /api/v1/sequencer/campaigns

Create a draft campaign.

curl -X POST "$APP_URL/api/v1/sequencer/campaigns" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Outreach","mailbox_ids":[10]}'

PATCH /api/v1/sequencer/campaigns/{campaign}

Update campaign fields, mailboxes, schedule, or settings. Set status to active on a draft campaign to activate.

Activation checks (HTTP 422 with failures[] when not met):

• check_circleAt least one email or follow-up step in the sequence
• check_circleAt least one verified, exclusive sender mailbox
• check_circlesettings.daily_send_limit > 0
• check_circleAt least one enrolled lead (or non-empty linked lead list)
• check_circleValid sending_window with non-empty days and start/end hours

curl -X PATCH "$APP_URL/api/v1/sequencer/campaigns/1" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {"daily_send_limit": 50, "schedule_mode": "future"},
    "sending_timezone": "America/Chicago",
    "sending_window": {
      "days": [1,2,3,4,5],
      "start_hour": 9,
      "start_minute": 0,
      "end_hour": 17,
      "end_minute": 0
    },
    "status": "active"
  }'

POST /api/v1/sequencer/campaigns/{campaign}/enroll

Enroll leads by lead_ids[] or bulk via lead_list_id. Requires at least one mailbox on the campaign (HTTP 422 otherwise).

curl -X POST "$APP_URL/api/v1/sequencer/campaigns/1/enroll" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids":[10,11]}'

Response: {"status":"completed","enrolled":2,"skipped":0} (HTTP 201).

POST /api/v1/sequencer/campaigns/{campaign}/pause|resume

Pause or resume an active/paused campaign.

GET /api/v1/sequencer/campaigns/{campaign}/analytics

Returns funnel metrics, engagement rates, and breakdowns:

{
  "data": {
    "campaign_id": 1,
    "funnel": {
      "total_enrolled": 100,
      "sent": 80,
      "opened": 40,
      "clicked": 12,
      "replied": 5,
      "bounced": 2
    },
    "rates": {
      "open_rate": 50.0,
      "click_rate": 15.0,
      "reply_rate": 6.25,
      "bounce_rate": 2.5
    },
    "by_mailbox": [],
    "by_step": [],
    "by_domain": []
  }
}

Interpreted in sending_timezone.

Register sequencer events on existing webhooks (POST /api/v1/webhooks, webhook permission). See Webhooks for HMAC verification.

• check_circlesequencer.email.sent
• check_circlesequencer.email.opened
• check_circlesequencer.email.clicked
• check_circlesequencer.lead.replied
• check_circlesequencer.lead.bounced
• check_circlesequencer.lead.unsubscribed
• check_circlesequencer.campaign.completed

The Mails.now MCP server exposes:

• check_circlelist_sequencer_leads (read)
• check_circlecreate_sequencer_lead (write + sequencer permission)
• check_circlelist_sequencer_campaigns (read)
• check_circleenroll_sequencer_campaign (write + sequencer permission)
• check_circlelist_sequencer_sequences (read)
• check_circlecreate_sequencer_sequence (write + sequencer permission)
• check_circlesync_sequencer_sequence_steps (write + sequencer permission)

Sequencer paths are included in /openapi.json under the Sequencer tag.

Interactive reference: API docs