Skip to main content
A campaign writes to the people on your lists, one step at a time: a first email, a follow-up a few days later, and so on. You write the steps yourself or let AI write them, check how they read, and launch. From then on, the campaign queues each person’s messages and sends them from your mailboxes, until you stop them or the steps run out. Every campaign call is free. Before you start, you need:
Every campaign route shares one rate limit of 30 calls a minute and 1,000 a day for the whole organization. That includes the routes for steps, templates, knowledge hubs and writing styles. Building one campaign takes a dozen calls, so pace your scripts. Poll a campaign, its leads or its queue every 10 seconds or slower, and when a call answers 429, wait the seconds in Retry-After.

Create a campaign

A new campaign is a draft. It writes to the people on up to 10 of your people lists, and sends nothing until you launch it.
A campaign’s status says where it is:
  • It starts with one empty step for each of its channels, ["email"] when left out. You write them next.
  • It sends from 9:00 to 17:00 in timezone (UTC when left out), on emailDays (Monday to Friday when left out).
  • Tracking is off until you turn it on: openRateTrackingEnabledAt and clickTrackingEnabledAt take the date-time it starts from. With click tracking on, links go through your tracking domain once you have an active one.
  • People can be left out with excludeLists, excludeCompanyLists, excludeContacted and excludeEngagedContacts. Every field is in Create a campaign. To leave a list out of every campaign at once, use an exclusion.

Let AI write the steps

With "type": "ai-generated" and a prompt that says what you offer and to whom, the steps are written for you, in the background:
Read the campaign with GET /v1/campaigns/{campaignId} until its initializationStatus is completed or failed. The steps draw on your default knowledge hub and follow your default writing style, unless you name others with knowledgeHubId and writingStyleId. A manual campaign’s initializationStatus is completed from the start. POST /v1/campaigns/{campaignId}/steps/regenerate writes the topics of a campaign’s AI steps again, from its knowledge hub. Messages already queued keep what they say.

Start from a template

templateId copies a saved template’s steps into the new campaign. They decide its channels, so send no channels with it. See Templates.

Write the steps

Write the first email

Read the new campaign’s steps to find the empty one:
Write it with a subject and a body, sent together: the two replace the step’s whole message, and one without the other answers 422. The body is HTML, and the variables in it are filled in for each person:
The answer is only the step’s id. Read the steps again to see the step as written.

Add a follow-up

It answers 201 with the new step, as the steps list shows it.
  • daysBetween is the wait: how many days after the step before this one goes out, 0 to 90. The first step counts from the start. There is no separate wait step.
  • sequenceNumber is the step’s place, from 0. Send the number of steps already there to add it at the end. A place another step holds answers 409 step_position_taken.
  • Other kinds of step: channel also takes linkedin_connection, linkedin_message, linkedin_visit, linkedin_like and inmail, which send from a connected LinkedIn seat. A step of "type": "ai_generated" writes each person’s message itself, and one of "type": "ai_reply" drafts a reply from your topic that waits for your approval. An ai_generated step answers once its topic is written, which can take a minute: allow two minutes.
  • Delete a step with DELETE /v1/campaigns/{campaignId}/steps/{stepId}, which answers 204.

Test two versions with an A/B split

An A/B split sends each person down one of two variants, a or b, so you can see which does better. It is a step with "channel": "condition", "conditionType": "ab_split" and "daysBetween": 0: a split waits for nothing, and any other daysBetween is refused. A split closes the sequence: the steps after it go in its variants.
splitArms gives each variant a label and the whole percent of people it gets. Left out, each gets 50. Then write variant a: a step whose parentStepId is the split and whose branchKey is a. Its sequenceNumber is its place in the variant, so the first one is 0:
Copy variant a into b, then change one thing in b:
The copies replace the steps b had. In GET /v1/campaigns/{campaignId}/steps they are the steps whose parentStepId is the split and whose branchKey is b: edit them with PATCH. In that list, sequenceNumber counts every step in the order it runs, variants included, so a variant’s steps carry higher numbers than their place in the variant. Change the weights at any time, with both variants adding up to 100. People not yet written to follow the new weights:
  • Add conditions before you launch. Once people move through a branched sequence, its steps can no longer be added, removed or moved: 409 sequence_structure_locked. Duplicate the campaign to change its shape.
  • Two other conditions wait for a signal, then send each person down the steps under yes or under no, as their branchKey: invite_accepted waits for a LinkedIn invitation to be accepted, and clicked_link for a click in an email, which needs click tracking on. Their daysBetween is how long they wait, 1 to 30 days.
  • A/B splits may not be on for your organization yet. Adding one then answers 422 ab_split_disabled.

Template variables

Variables are written in single braces, with these exact names. Each is filled in for the person a message is written for:
Write the names exactly as they are here. {First Name}, for one, is not a variable: it is sent as written, braces and all. Preview each step before you launch, and check that every variable was filled in.
A list’s own columns are variables too, by the column’s name in single braces, such as {Fit notes}. GET /v1/campaigns/{campaignId}/variables lists every variable a campaign can use, each with its token: the ones above first, then each column with the list it is on. A mailbox’s signature is set with PATCH /v1/accounts/email/{accountId}: see Connect sending accounts.

Preview a step

A preview writes a step for the first person on the campaign’s lists, as they would get it:
Nothing is saved or sent, and read-only keys may call it. A word still in braces is not a variable, and would go out as written. Writing an AI step can take a minute: allow two minutes. Previews have their own limit too: 20 a minute and 300 a day.

Send a test email

A test email writes an email step for one person and sends it to any address, such as your own:
  • It is a real email, and it goes at once. Every call sends one, and uses one of the sending mailbox’s emails for the day, its availableCapacity. To retry one safely, send an Idempotency-Key.
  • personId is who the step is written for: someone on one of the campaign’s lists. Left out, the first person of its first list.
  • fromEmail is the mailbox it goes from. Left out, the first active one. A mailbox that is not active and connected answers 422 email_account_not_available.
  • A test email carries no unsubscribe link and no tracking.
  • Test emails have their own limit: 10 a minute and 100 a day.

Check it is ready

Readiness runs the launch checks without launching:
When ready is false, reason is the code a launch would answer with, such as no_active_email_accounts (connect or resume a mailbox) or step_body_missing (a step has no body yet). people counts the people on the campaign’s lists. An email-only campaign skips those without a work email.

Launch

Launching is the only call that makes a campaign send. It runs the readiness checks first, and refuses with the first that fails, as 422 and its code. Then it answers 202 and enrolls the people on the campaign’s lists in the background: each one becomes a lead, and their first message is queued, as scheduled for a step you wrote. Follow the enrolling with the leads and the queue.
  • Campaign email leaves on the half hour, at :05 and :35 past each hour, so a message can go out up to 30 minutes after its scheduledAt. Test emails, direct messages and replies go at once.
  • Launching a running campaign changes nothing. Launching a paused one starts it again with the messages it had queued. It may first write its older AI messages again, so allow two minutes.

Pause

A paused campaign sends nothing, and its queued messages wait. Launch it again to send them. While a launch or a pause of the same campaign is still running, another one answers 409 campaign_busy: try again in a few seconds.

Add people to a running campaign

Add a list

In a running campaign, the list’s people are enrolled in the background (enrollmentStarted). In a draft, they are enrolled at launch. A campaign holds up to 10 lists. Changing listIds with PATCH /v1/campaigns/{campaignId} replaces the lists but enrolls nobody in a running campaign, so add lists this way. Adding lists has its own limit too: 500 a day.

Add people by id

To enroll a few people without adding them to a list, send their ids, 1 to 60 a call:
  • Each person comes back with an outcome: added, already_in_campaign, missing_valid_email, missing_linkedin, person_not_found or enrollment_failed. Sending the call again enrolls nobody twice.
  • Nothing is looked up here. Find missing emails first with enrichment.
  • Only a running campaign takes people this way. A draft or a paused one answers 409 campaign_not_active: add a list to it instead.
  • Adding people has its own limit too: 10 a minute and 500 a day.

Follow the leads

Each person enrolled is a lead:
A lead shows where the person is in the sequence (sentSteps of totalSteps), what they did, the variants they were given and the account that first wrote to them. search finds a name or a company. Page through with cursor: see Pagination.

Stop and resume a lead

Stopping a lead sends them nothing more from the campaign. Use the lead’s id, not its personId:
It answers 204, and so does stopping a lead that is already stopped. Resuming starts the lead again from where it stopped, and answers with its next message, queued at once:
To stop one person in several campaigns at once, such as when they answer you elsewhere, use their personId:
It answers 204. A person in none of the campaigns answers 404 person_not_in_campaign, and nothing is stopped.

Work the send queue

Every message a campaign writes waits in its queue until it goes out. List the messages in one state with status, which is required:

Edit a message

Change a message that is still waiting to go out: its subject, its body, or when it goes (scheduledAt, in UTC).
An edit makes a new message: the answer’s id is the new one, and the message you edited becomes overwritten. Use the new id from then on. Editing the old one, or a message that already went out, was skipped or was declined, answers 409 send_not_editable.

Skip a message

The message is not sent, and its person moves on to their next step. Skipping a message that is already skipped changes nothing.

Approve or decline messages

Messages written by AI can wait for your approval, as approval_required. Approve up to 100 at a time, and they become scheduled:
POST /v1/sends/decline takes the same body. Declined messages become stopped, and their people’s sequences in the campaign end. In both answers, notFound holds the ids your organization does not have, and ignored the messages that could not change: approving takes only messages waiting for approval, and declining only messages that have not gone out.

Read the results

  • GET /v1/campaigns/{campaignId}/stats counts the messages sent, the people who opened and clicked, and the replies, since since (12 months ago when left out). Opens and clicks are counted only while tracking is on.
  • GET /v1/campaigns lists every campaign with the same counts and their rates. Narrow it with status, type or search.
  • GET /v1/campaigns/{campaignId}/ab-results shows each A/B split: its variants and their weights, and how each variant did, in all and since the weights last changed: the people it reached, replies, positive replies, meetings, bounces and unsubscribes. isSmallSample is true while there are too few people to tell the variants apart.

Change a campaign

PATCH /v1/campaigns/{campaignId} changes a campaign’s settings: its name, start, sending days and time zone, lists and exclusions, tracking, daily limits and ctaLink.
  • It answers the campaign as GET /v1/campaigns/{campaignId} does: its name, type, status, lists and daily limits, and the settings it holds, under the names you set them with: startDate, timezone, emailDays, isDynamic, the four exclusions, addUnsubscribeLink, openRateTrackingEnabledAt, clickTrackingEnabledAt and ctaLink. A setting with no value is left out.
  • Click tracking stays on while a step waits for a click: turning it off answers 409 click_tracking_required_by_condition.
  • POST /v1/campaigns/{campaignId}/duplicate copies a campaign, with its settings and steps, into a new draft named Copy of and the original’s name.

Unsubscribes

  • Every campaign email ends with a one-click unsubscribe link, unless you create or change the campaign with "addUnsubscribeLink": false.
  • A send to someone who unsubscribed is refused. A message, a reply or a test email to an address that unsubscribed from the mailbox’s emails answers 422 recipient_unsubscribed, and nothing is sent.
  • Do not resume a lead who unsubscribed. Resuming restarts a lead whatever stopped it, an unsubscribe included.

Exclusions

An exclusion leaves one of your lists out of every campaign of your organization: the people on a people list, or the people at the companies on a company list. Use it for your customers, your competitors, or anyone campaigns should not write to.
  • It works when a campaign enrolls people from its lists: at launch, when you add a list to it, and, in a campaign with isDynamic, as people join its lists. People and companies you add to the excluded list later are left out too.
  • A company list covers the people linked to its companies. A person is left out when the company their record is linked to is on the list. A company name alone does not match.
  • It does not stop anyone already enrolled, and it does not cover people you add by id with POST /v1/campaigns/{campaignId}/people. To stop someone who is already in campaigns, see Stop and resume a lead.
  • GET /v1/exclusions lists your exclusions, oldest first. matchedPeopleCount counts the checks that left a person out, so it grows faster than the people left out: a campaign with isDynamic checks its lists again every 30 minutes.
  • DELETE /v1/exclusions/{exclusionId} stops excluding the list and answers 204. The list is kept. The people it left out are enrolled by the next enrollment: a running campaign with isDynamic takes them from its lists within 30 minutes.
  • One list, one exclusion. A list you already exclude answers 409 list_already_excluded, and a list kept automatically, such as the list of people who unsubscribed, answers 422 list_not_excludable.
  • Exclusion calls have their own limit, apart from the campaign routes’: 30 a minute and 2,000 a day.

Tracking domain

With click tracking on, each link in a campaign’s emails goes through a link address, where a short redirect page counts the click and sends the person on. A tracking domain makes that address a hostname of your own, such as go.fernway.co, so the people you write to see your domain when they hover a link. Your organization has one at a time, and every campaign with click tracking on uses it once it is active.
Now add one CNAME record at your DNS provider: its name is the hostname, and its value is dnsTarget. The domain’s status says where it is: The domain is checked every 5 minutes for about a day. Once the record is found, it usually becomes active within half an hour, and it can pass through pending_dns and verifying more than once on the way.
  • Check it now with POST /v1/tracking-domains/{trackingDomainId}/verify once the record is in place, instead of waiting for the next check. It answers the domain as the check left it.
  • Follow it with GET /v1/tracking-domains, which lists your tracking domain. With ?activeOnly=true it is listed only while it is active.
  • It takes a subdomain of at least three labels. fernway.co answers 422 invalid_tracking_hostname. A hostname another organization holds answers 409 tracking_hostname_already_claimed, and a second tracking domain 409 tracking_domain_limit_reached.
  • It covers tracked links in campaign emails only. A campaign with click tracking off sends its links as you wrote them. The open tracking image, the unsubscribe link, test emails and messages you send outside a campaign do not go through it.
  • DELETE /v1/tracking-domains/{trackingDomainId} answers 204, and new emails send their links through the shared link address again. Links in emails already sent keep working only while the CNAME record stays in place, so keep the record. While the domain is still being switched off the delete answers 409 tracking_domain_removal_pending: send it again in a minute or two.
  • Adding a hostname you deleted brings the same domain back, with the id it had, if it was ever active.
  • Tracking domain calls have their own limit, apart from the campaign routes’: 30 a minute and 1,000 a day. Adding, checking and deleting one share a tighter one on top: 10 a minute and 200 a day.

Templates

A template keeps a campaign’s steps and schedule (sending days, hours, time zone and lists), to start new campaigns from:
Start a campaign from it with templateId on POST /v1/campaigns. GET /v1/campaign-templates lists up to 100 templates with their steps, and DELETE /v1/campaign-templates/{templateId} deletes one. Campaigns made from it keep their steps.

Knowledge hubs

AI steps write from your knowledge hub: pages about your company, its products, pricing, customers and competitors, built from your websites and notes. Your organization has one hub, its default. Create it once:
It answers 202 with the hub processing while its sites are read, which takes minutes. Read it with GET /v1/knowledge-hubs/{hubId} until its status is complete, or draft if building failed. Then read its pages with GET /v1/knowledge-hubs/{hubId}/pages.
  • Find it again with GET /v1/knowledge-hubs, which lists your hubs, the default first.
  • Add to it with PATCH /v1/knowledge-hubs/{hubId}: new websites and notes are read in the background, and nothing is removed. A second hub answers 409 knowledge_hub_already_exists.
  • Pages are written in Markdown. Add your own with POST /v1/knowledge-hubs/{hubId}/pages, change one with PATCH /v1/knowledge-hubs/{hubId}/pages/{pageId}, or delete it with DELETE on the same path. POST /v1/knowledge-hubs/{hubId}/pages/{pageId}/regenerate writes a page again from its sources; a page you wrote yourself has none, and answers 409 knowledge_page_not_regenerable.
  • Read a website again with POST /v1/knowledge-hubs/{hubId}/refresh, sending its url.
  • The default hub cannot be deleted: 409 knowledge_hub_default_undeletable.

Writing styles

GET /v1/writing-styles lists your organization’s writing styles, the default first. An ai-generated campaign follows the style its writingStyleId names, or your default.

Delete a campaign

It answers 204, and nothing more is sent from the campaign. Its people and lists are kept. Deleting it again answers 404 campaign_not_found.

Keys and limits

  • Keys. Campaign calls need a key with the campaigns scope. Read-only keys can read campaigns, their steps, leads, queue and stats, templates, knowledge hubs, writing styles, exclusions and the tracking domain, and preview steps. Everything else needs a key that can write.
  • Rate limits. Every campaign route shares one rate limit: 30 calls a minute and 1,000 a day. Some routes have their own on top: adding lists (500 a day), adding people (10 a minute, 500 a day), previews (20 a minute, 300 a day), rewriting AI steps (10 a minute, 100 a day), copying variants (20 a minute, 300 a day) and test emails (10 a minute, 100 a day). Exclusions and the tracking domain do not draw on it: each has its own limit.