launch_campaign
Create and activate a campaign on a lead list. You supply name, offer, leads[], sequence[] (per step: subject, body, delayDays — subject is REQUIRED on step 1; a LATER step may omit it to keep step 1's subject line [recommended], which resolves at launch to "Re: " + step 1's subject (unchanged if that already starts with "Re: "), or set one explicitly to change only that step's subject line — every later step is still sent In-Reply-To step 1, though some mail clients display a changed subject as a separate conversation), and optionally timezone, sendWindow, stopOnReply, listSource (one sentence on where the list came from — REQUIRED on a crowdfunding account, where a missing or "unknown" source is refused 400) — the platform does not write copy. Each step's step number must be unique within the sequence; a duplicate step number is refused (400) naming it. Subjects and bodies may use {{firstName}} and {{company}} (filled from each lead); a launch is refused (400) if any subject or body uses any other {{token}}, a single-brace form of a known token such as {firstName} or {company} (a typo for the double-brace form — it would otherwise reach the recipient unsubstituted), or a run of 3 or more consecutive { or } anywhere (e.g. {{{firstName}}} or a lopsided run like {{{firstName}} — it would otherwise reach the recipient with stray braces attached). The send window is evaluated in timezone (IANA, e.g. America/New_York; default UTC) — set it to your recipients' zone. sendWindow is { startHour, endHour, days? }: integer hours 0-23, endHour INCLUSIVE (the last hour a send may start in), days 0=Sunday … 6=Saturday. Each omitted field (or all of them, by omitting sendWindow) gets the platform's RECOMMENDED default {"startHour":8,"endHour":16,"days":[1,2,3,4,5]} — Monday-Friday business hours — except on a sandbox account, where omitted fields are open every hour of every day until it upgrades and they take that default; the decision is yours, e.g. include 0 and 6 in days to send on weekends. Setting exactly ONE of startHour/endHour combines it with the recommended default for the OTHER (08/16, including on a sandbox account, since that value re-resolves to the same default on upgrade) — if that combination would wrap the window past midnight (start > end), the launch is refused; set both explicitly, including for a deliberate overnight window such as {startHour:22, endHour:6}. Step 1 goes out from the least-loaded mailbox; each later step goes out delayDays after the previous step ACTUALLY sent, from the SAME mailbox, with In-Reply-To/References set to step 1's Message-ID — it waits while that mailbox is at its daily cap, and the lead's remaining steps are cancelled (a 'failed' event says why) once that mailbox is paused or released, since neither ever lifts on its own, or when a paid account's thread went out from a connected BYO mailbox, which this build never sends from; a step whose previous step never went out is skipped. Suppressed leads are skipped. Returns { campaignId, sendWindow, timezone, nextSteps } — sendWindow and timezone are what actually applied. Campaigns send real mail, so a launch identical to one this account made in the last 60 seconds is REFUSED with 409 { code:'duplicate_campaign', existingCampaignId } rather than contacting the same prospects twice — check that campaign instead of relaunching. Resend the same idempotencyKey to retry a call whose response you lost: that replays the original result instead of being refused. Campaigns that differ in any field other than listSource (which is not part of that check), and deliberate relaunches after those 60 seconds, are never blocked.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| endBy | No | Optional fixed end date, as an ISO 8601 instant with a zone. From then on nothing more in this campaign sends: every step still waiting is skipped and recorded as a 'failed' event with reason campaign_ended. Paid accounts only: a trial account that sends one is refused 400. Must be later than now and later than every step's notBefore. Omit to let the sequence run to its end. | |
| leads | Yes | ||
| offer | Yes | ||
| sequence | Yes | ||
| timezone | No | IANA time zone the send window is evaluated in — set it to your recipients' zone. Default UTC. | UTC |
| listSource | No | Where this lead list came from, in a sentence (e.g. "our own past-donor CRM export"). REQUIRED on a crowdfunding account: a launch with no source, or "unknown", is refused (400) — cold lists are allowed only with a stated source. Optional elsewhere. Max 500 characters. | |
| sendWindow | No | Integer hours 0-23 (endHour inclusive: the last hour a send may start in) and weekdays, evaluated in `timezone`. Each field you omit (or all of them, by omitting sendWindow) gets the recommended {"startHour":8,"endHour":16,"days":[1,2,3,4,5]} — except on a sandbox account, where omitted fields are open every hour of every day until it upgrades and they take the recommended default. If you set exactly ONE of startHour/endHour, the other still defaults to the recommended value (08/16) — if that combination would wrap past midnight (start > end), the launch is refused; set both explicitly, including for a deliberate overnight window. | |
| stopOnReply | No | ||
| idempotencyKey | No | Optional idempotency key: resend the SAME key when retrying this call so a dropped-response retry is not applied twice (no duplicate campaign/provision/send). |