--- title: "Create a campaign" method: POST path: "/campaigns" tags: ["Campaigns"] --- # Create a campaign `POST /campaigns` ## Request - Base URL: `https://warmysender.com/api/v1` - URL: `https://warmysender.com/api/v1/campaigns` - Auth: HTTP bearer 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`. Requires a unique `Idempotency-Key` request header so retries never duplicate. ## Headers - `Idempotency-Key` string, required ## Request body - object - `name` string, required: Campaign name. - `description` string: Optional description. - `channel` 'email' | 'linkedin' | 'whatsapp' | 'instagram' | 'multichannel': Campaign channel. A single-channel campaign may only carry steps of that channel (plus condition steps); mix channels only under "multichannel". - `linkedinAccountId` string, uuid: LinkedIn account id (for linkedin/multichannel). - `instagramAccountId` string: Instagram account that sends this campaign. Required when the campaign carries Instagram steps. Needs an active Instagram seat. - `whatsappAccountId` string: WhatsApp number that sends this campaign. Required when the campaign carries WhatsApp steps. Needs an active WhatsApp seat. - `timezone` string: Timezone the sending window and days are read in, as a name like "Europe/Paris" or "America/New_York". Leave it out to use your workspace timezone (Settings → Workspace), which is UTC unless you changed it. - `dailySendLimit` integer: Daily send cap for the campaign. - `sendingWindowStart` integer: Start hour (0–23) of the daily sending window. - `sendingWindowEnd` integer: End hour (0–23) of the daily sending window. - `scheduleDays` integer[]: Days of the week this campaign may send on. Numbers use 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday (Sunday is 0, not Monday). Day names such as "mon" or "monday" are accepted too and are the safest choice. Order and repeats do not matter. Leave it out for Monday–Friday [1,2,3,4,5]; an empty list is refused because a campaign with no sending days could never send. - `stopOnReply` boolean: Stop a prospect's sequence when they reply. - `stopOnBounce` boolean: Stop on bounce. - `stopOnUnsubscribe` boolean: Stop on unsubscribe. - `trackOpens` boolean: Track opens. - `trackClicks` boolean: Track clicks. - `opt_out_style` '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` string, 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 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. - `company_address` string, nullable: The postal address shown in the footer of THIS campaign's emails — useful when you run campaigns for several companies from one workspace. Leave it out and the campaign keeps using your workspace address; send null (or an empty string) to go back to it. - `startDate` string, date-time: Optional scheduled start. - `endDate` string, date-time: Optional end date. - `steps` object[], required: 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` string: Subject line of an email step. Merge tags and spintax work here. Optional when the step reuses a template that carries one. - `steps[].preheader` string: Preview text shown after the subject line in the inbox. - `steps[].bodyHtml` string: HTML email body. Use simple HTML:

,
, , , , ,