Campaigns

Campaigns

Start date and daily cap

• startAt: an ISO date-time with an offset (e.g. 2026-10-13T09:00:00+05:30). Nothing is sent before it; after it, the normal send window and days apply. null clears it.
• dailyNewLeadCap: the most leads that get their first email from this campaign per day (1 to 100000). Follow-ups are not counted and not limited by it. The day is the campaign’s defaultTimezone day, or the UTC day if it has none. null = no cap.
• folder: a free-text label to group campaigns; filter with GET /campaigns?folder=.

Stats

GET /campaigns, GET /campaigns/:id/stats and the CSV reports count the same way:

opensTracked and clicksTracked say whether the campaign tracks opens and clicks. When one is false, its numbers mean nothing; the dashboard shows them blank.

Deleting a campaign

DELETE /campaigns/:id deletes the campaign with its steps, settings, mailbox pool and lead links. It returns { deleted, id, leadsDeleted, leadsKept }.

• With ?deleteLeads=true, every lead of the campaign that is in no other campaign is deleted too, with its replies and tags. A lead that is also in another campaign is kept.
• Sent emails are kept. They count for mailbox daily limits, the plan’s quota and bounce health.
• Suppression list entries are kept.

Call GET /campaigns/:id/delete-preview first to see the counts.

Only an owner or admin can delete. Through an API key the rules are stricter: only a DRAFT that has never sent can be deleted (409 otherwise; archive it instead), and deleteLeads=true returns 403. Deleting a campaign with history is done in the dashboard.

Launch guard

GET /campaigns/:id/launch-check returns ready, blockers and warnings, each with a code and a message:

Setting a campaign to ACTIVE while it has warming mailboxes or template-token problems returns 409 with code: "LAUNCH_NEEDS_CONFIRMATION" and the launch report. Send the same request again with confirm: true to start anyway.

Leads on a campaign

POST .../leads returns a per-lead result: assigned, suppressed, no_eligible_mailbox, seg_blocked, or error — a lead that can’t be assigned yet is still added, unassigned, so nothing is silently dropped.

.../leads/reassign only moves leads that have not been emailed yet by this campaign (a lead already in conversation keeps its mailbox, so the thread stays with one sender). It returns reassigned, leftUnassigned, skippedAlreadyEmailed and more.

Sequence steps

subject, bodyTemplate and bodyHtmlTemplate accept these variables:

Write them in double braces, spelled exactly as below. They are case-sensitive. A misspelt variable is not replaced: it is sent as written, so {{sender_signature}} or {{Signature}} would reach the lead as literal text.

• A lead field that is empty for a lead becomes empty text, not the raw {{token}}.
• Signature: put {{signature}} where you want it, and it goes exactly there (plain-text or HTML signature, each part of the email gets the right form). A step without {{signature}} still gets the signature, added at the bottom automatically. It is never added twice. If the mailbox has no signature, the variable’s line is removed cleanly.
• Every lead is sent from its own assigned mailbox, so {{senderName}} and {{signature}} are that mailbox’s, not one global value.

Step attachments

A step’s files are sent with every lead’s email for that step, and with test sends. Duplicating a campaign copies them.

• A step’s files and images can be 10 MB in all (413 over that).
• fromAttachmentId copies a file already in an inbox conversation, by the attachment id from GET /replies/thread/:leadId (for example a deck you sent by hand in a reply), so you don’t upload it again. 404 if no such file is in your workspace.
• inline: true adds an image to show inside the body: PNG, JPEG, GIF or WebP, 1 MB at most. The response has a cid. Show it in bodyHtmlTemplate as <img src="cid:THE_CID">.
• An inline image is sent only when the body shows it. Saving a body that no longer shows it removes it.
• The list returns id, filename, contentType, size and cid. Inline images also come with dataBase64.

A step with no bodyHtmlTemplate is sent as plain text, unless the campaign tracks opens (open tracking needs an HTML part, so one is made from the text).

A/B variants and follow-ups

Several steps with the same stepOrder and a different variantGroup are variants of one step.

• Each step picks its variant on its own. A lead that got variant A of step 1 can get variant B of step 2. (With abVariantOptimization on, the pick leans towards the variant with the better reply rate; otherwise it is random.) If the follow-ups must match the first email, give the follow-up steps a single version.
• Follow-ups are replies in the same thread. Every step after the first (stepOrder above 0) goes from the same mailbox as Re: + the subject of the first email the lead got, with In-Reply-To / References pointing at the earlier emails, so the lead sees one conversation. A follow-up’s own subject is not used, so it is optional; the first step needs one.

Mailbox pool

Changing the pool does not move leads already assigned. leadsOutsidePool tells you how many leads are on a mailbox that left the pool; call POST .../leads/reassign to move the ones not yet emailed.

Copy fatigue

CRM

Check a step before sending

POST /campaigns/:id/steps/preview body: stepId (a saved step) or subject + bodyTemplate (+ bodyHtmlTemplate) to check a draft; optional leadId (any lead in the workspace; default: the campaign’s first lead) and mailboxId (default: that lead’s assigned mailbox). It runs the same code as the real send, so subject, text and html are what the lead gets (the tracking pixel and click redirects are left out). The response also has signature (at_token, appended_at_bottom or none), variables (used, unknown = would be sent as literal text, malformed, empty for this lead) and plain-English notes.

GET /campaigns/:id/variables-check returns, per step, the tokens used, unknown and empty tokens with how many leads each affects, and malformed text; ok is true when no lead would receive a raw {{token}}. Run it before starting a campaign.

Campaign settings and timezone

The send window (sendWindowStartHour / sendWindowEndHour on the campaign) is in each lead’s own timezone when the lead has one, otherwise in defaultTimezone. Set defaultTimezone to an IANA zone from /timezones (e.g. America/New_York, Asia/Kolkata); an unknown zone is rejected with a 400. With no timezone at all, a lead can be emailed at any hour.