Campaigns

Every Emelia campaign is multichannel: email steps, LinkedIn steps, WhatsApp messages, manual tasks and conditions live in the same sequence. Its steps decide its channels, so a cold email campaign and a LinkedIn automation campaign are created the same way.

A campaign is built in a few calls:

1. Create the campaign
2. Write the sequence
3. Set the schedule
4. Choose the senders
5. Attach the contacts
6. Send yourself a test
7. Start it

The examples use this setup:

export EMELIA_API_KEY="your_api_key"
export CAMPAIGN_ID="6650f1a2b839d80011c5a0f1"

1. Create the campaignCopy Anchor Link

curl -X POST https://api.emelia.io/advanced/campaigns \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q4 SaaS founders", "timeZone": "Europe/Paris"}'
# {"success":true,"campaignId":"6650f1a2b839d80011c5a0f1"}

The name must be unique on your account. The campaign is created as a DRAFT, with a sequence that only holds the START step, and these defaults:

2. Write the sequenceCopy Anchor Link

The sequence is a tree of steps, sent whole in steps: an object, the root of the tree, not an array. The call replaces the whole tree, and the campaign must not be running.

A cold email sequenceCopy Anchor Link

Three emails, three then five days apart:

curl -X PATCH "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/steps" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @sequence.json

{
  "steps": {
    "_id": "START",
    "stepType": "START",
    "delay": { "amount": 0, "unit": "DAYS" },
    "next": {
      "stepType": "EMAIL",
      "delay": { "amount": 0, "unit": "DAYS" },
      "versions": [
        {
          "subject": "{{companyName}} and Postgres 16",
          "message": "<p>Hi {{firstName}},</p><p>I saw {{icebreaker}}. ...</p><p></p><p>{{signature}}</p>",
          "disabled": false
        }
      ],
      "next": {
        "stepType": "EMAIL",
        "delay": { "amount": 3, "unit": "DAYS" },
        "versions": [
          {
            "subject": "",
            "message": "<p>Following up, {{firstName}}. ...</p><p></p><p>{{signature}}</p><p></p><p><a href=\"{{unsubscribe_link}}\">Unsubscribe</a></p>",
            "disabled": false
          }
        ],
        "next": {
          "stepType": "EMAIL",
          "delay": { "amount": 5, "unit": "DAYS" },
          "versions": [
            {
              "subject": "",
              "message": "<p>Last note from me, {{firstName}}. ...</p><p></p><p>{{signature}}</p><p></p><p><a href=\"{{unsubscribe_link}}\">Unsubscribe</a></p>",
              "disabled": false
            }
          ]
        }
      }
    }
  }
}

• The body is HTML. One <p> per paragraph, <p></p> for an empty line.
• An empty subject keeps the thread: the follow up arrives as a reply to the previous email. The first email needs a subject.
• Several versions on an EMAIL step make an A/B test: each contact gets one of them. disabled: true takes a version out of the rotation.
• cc on an EMAIL step copies an address, which can be a variable such as {{assistantEmail}}.

A LinkedIn automation sequenceCopy Anchor Link

Visit the profile, send an invitation, then two messages once it is accepted. Send it with the same call.

{
  "steps": {
    "_id": "START",
    "stepType": "START",
    "delay": { "amount": 0, "unit": "DAYS" },
    "next": {
      "stepType": "VISIT",
      "delay": { "amount": 0, "unit": "DAYS" },
      "versions": [{}],
      "next": {
        "stepType": "CONNECTION",
        "delay": { "amount": 1, "unit": "DAYS" },
        "versions": [{ "message": "" }],
        "next": {
          "stepType": "MESSAGE",
          "delay": { "amount": 2, "unit": "HOURS" },
          "versions": [
            { "message": "Thanks for connecting, {{firstName}}. I work with teams like {{companyName}} on ..." },
            { "message": "{{firstName}}, would a 15 minute call next week make sense?" }
          ]
        }
      }
    }
  }
}

• An empty note on CONNECTION sends the invitation without a message.
• A MESSAGE step placed right after a CONNECTION waits for the invitation to be accepted, for up to a year.
• On MESSAGE and WHATSAPP steps, the versions are successive messages sent in order, not an A/B test.
• dailyLinkedinAdded is capped at 40 new contacts per day when the sequence sends invitations, 80 otherwise.

A multichannel sequence with a conditionCopy Anchor Link

LinkedIn first. If the invitation is accepted within 5 days, a LinkedIn message. If not, and the contact has an email, two emails.

{
  "steps": {
    "_id": "START",
    "stepType": "START",
    "delay": { "amount": 0, "unit": "DAYS" },
    "next": {
      "stepType": "CONNECTION",
      "delay": { "amount": 0, "unit": "DAYS" },
      "versions": [{ "message": "" }],
      "next": {
        "stepType": "CONDITION",
        "delay": { "amount": 5, "unit": "DAYS" },
        "conditions": { "field": "ACCEPTED", "operator": "EQUAL", "value": "true" },
        "yes": {
          "stepType": "MESSAGE",
          "delay": { "amount": 2, "unit": "HOURS" },
          "versions": [{ "message": "Thanks for connecting, {{firstName}}. ..." }]
        },
        "no": {
          "stepType": "CONDITION",
          "delay": { "amount": 1, "unit": "HOURS" },
          "conditions": { "field": "$email", "operator": "IS_NOT_EMPTY", "value": "" },
          "yes": {
            "stepType": "EMAIL",
            "delay": { "amount": 1, "unit": "DAYS" },
            "versions": [{ "subject": "{{companyName}} and Postgres 16", "message": "<p>Hi {{firstName}},</p><p>...</p><p></p><p>{{signature}}</p>", "disabled": false }],
            "next": {
              "stepType": "EMAIL",
              "delay": { "amount": 4, "unit": "DAYS" },
              "versions": [{ "subject": "", "message": "<p>...</p><p></p><p>{{signature}}</p><p></p><p><a href=\"{{unsubscribe_link}}\">Unsubscribe</a></p>", "disabled": false }]
            }
          },
          "no": { "stepType": "END_OF_CAMPAIGN", "delay": { "amount": 0, "unit": "DAYS" } }
        }
      }
    }
  }
}

Step and version ids: ObjectIds, never UUIDsCopy Anchor Link

The API accepts any string without an error, so a wrong id is not caught when you save the sequence. If you must write ids yourself, for example to keep a reference in your system, generate real ObjectIds:

# 24 lowercase hexadecimal characters
openssl rand -hex 12

Anatomy of a stepCopy Anchor Link

There is no WAIT step: a wait is the delay of the next step. LinkedIn step types have no LINKEDIN_ prefix. FOLLOW, AUDIO and API_CALL exist in the model and are accepted when you save the sequence, but nothing runs them: no action happens and the step is never marked as done. Do not use them. A voice note is a MESSAGE step, see Attachments and voice notes.

ConditionsCopy Anchor Link

A CONDITION step has a conditions object, a yes branch and a no branch. field takes two forms:

• The delay of an event condition is its observation window. "Accepted within 5 days?" keeps the contacts that have not accepted on hold for 5 days, then sends them down no. A field condition is evaluated at once.
• Only the operators above are evaluated. Any other value, for example NOT_EQUAL or GREATER_THAN, is saved without error and always evaluates to false: everybody goes down no.
• {{email}} is not a valid field: write $email.
• OPENED and CLICKED need tracking (trackOpens, trackLinks). Without it the event is never recorded and everybody goes down no.
• Branches never join again. A step needed after both branches is written in each of them.

VariablesCopy Anchor Link

Write variables as {{name}} in subjects and messages:

• the contact fields firstName, lastName, fullName, email, secondaryEmail, phone, mobilePhone, jobTitle, seniority, department, gender, age, language, linkedinUrlProfile, twitterUrl, country, region, city, postalCode, address, timezone, yearsOfExperience, education, bio, companyName;
• every custom variable of your contacts, for example {{icebreaker}};
• the company fields, with companyCountry and companyCity for the country and city of the company;
• {{signature}}, the signature of the sending mailbox, and {{unsubscribe_link}}, the unsubscribe URL to put in a link.

Messages also support spintax: {Hi|Hello|Hey} {{firstName}} picks one of the options for each contact. Check that every contact has a value for the variables you use, then send yourself a test (step 6) before you start.

Attachments and voice notesCopy Anchor Link

Upload the files first, then reference their URL in versions[].attachments of an EMAIL, MESSAGE or WHATSAPP step. Uploaded files get a public URL: anyone with the link can download them.

curl -X POST https://api.emelia.io/advanced/attachments \
  -H "Authorization: $EMELIA_API_KEY" \
  -F "attachments=@./brochure.pdf"

Up to 3 files of 20 MB per call. A LinkedIn voice note goes through its own route (webm, 10 MB and 5 minutes at most), which returns its url and its duration in milliseconds, to attach with "mediaType": "AUDIO":

The voice note itself is a MESSAGE step, not a step type of its own: put the recording as the attachment of its first version, with the name, url and duration the upload returned. duration stays in milliseconds (32000 is 32 seconds).

{
  "stepType": "MESSAGE",
  "delay": { "amount": 2, "unit": "DAYS" },
  "versions": [
    {
      "message": "",
      "attachments": [
        { "name": "voice-note.m4a", "url": "https://...", "mediaType": "AUDIO", "duration": 32000 }
      ]
    }
  ]
}

A MESSAGE step whose first attachment has no url blocks the start with LINKEDIN_AUDIO_MISSING.

3. Set the scheduleCopy Anchor Link

curl -X PATCH "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/settings" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "timeZone": "Europe/Paris",
      "days": [0, 1, 2, 3, 4],
      "start": "09:00",
      "end": "17:30",
      "dailyEmailAdded": 20,
      "dailyEmailLimit": 60,
      "trackOpens": false,
      "trackLinks": false,
      "blacklistUnsub": true,
      "ignoreAutoReplies": true
    }
  }'

The fields you send in settings are merged into the current settings. Always send start, end, trackOpens, trackLinks and blacklistUnsub: the call fails without them. The simplest is to read the campaign, change its schedule and send it back.

4. Choose the sendersCopy Anchor Link

An identity is a sender: a name, plus an email provider, a LinkedIn account, a WhatsApp account, or several of them. For each step, Emelia picks the least used identity that has an account on the channel.

Get the ids of your mailboxes with List email providers (_id, and skip the ones marked disconnected). LinkedIn and WhatsApp accounts are connected in the Emelia app; there is no documented route to list them yet: set them in the app, or reuse the ids found in the identities of an existing campaign (GET /advanced/campaigns).

curl -X PATCH "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/identities" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identities": [{"name": "Marie Martin", "email": "6650f1a2b839d80011c5a0aa", "linkedin": "6650f1a2b839d80011c5a0bb"}]}'

The array replaces the identities of the campaign. With an email step, every identity needs an email provider. With a LinkedIn step, use one LinkedIn account shared by all identities, or one per identity: otherwise the start fails with LINKEDIN_ACCOUNT_AMBIGUOUS. On an agency account, attach only the mailboxes of this client.

5. Attach the contactsCopy Anchor Link

Contacts live in lists. Attach one or several lists, and optionally lists to exclude:

curl -X PATCH "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/recipients" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lists": ["66f1c0ffee5a7d3b2c4e8a10"]}'

lists replaces the whole selection. A contact whose email or LinkedIn URL is in one of the excludedLists is left out. This call works on a running campaign, and every contact added to an attached list later joins the campaign on its own. A campaign starts with 30,000 recipients at most.

To add one contact straight to a campaign, without managing a list, use Add a contact to a campaign. Emelia stores it in a list named "<campaign name> contacts from API". A running campaign schedules it at once, and a finished campaign starts again on its own. Only email, linkedinUrlProfile, phone, firstName and lastName are native fields there; every other key becomes a custom variable, and every value must be a string.

6. Send yourself a testCopy Anchor Link

Take the _id of the email step and of its version from Get a campaign, after step 2. The test uses the variables of a random contact of the campaign.

curl -X POST "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/test-email" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stepId": "6650f1a2b839d80011c5c001", "versionId": "6650f1a2b839d80011c5c002", "email": "you@yourcompany.com"}'

7. StartCopy Anchor Link

curl -X POST "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/start" \
  -H "Authorization: $EMELIA_API_KEY"

The start needs an active subscription and runs every check at once. The first that fails is returned with a stable error code: NO_IDENTITY_SET, EMAIL_VERSION_NO_SUBJECT, NO_RECIPIENTS, RECIPIENTS_NO_EMAIL... Contacts are scheduled in the background after the response.

To start later, set a date with Schedule a planned start ({"plannedStart": "2026-10-20T08:00:00.000Z"}, at least in the future), and send null to cancel it. The same checks run when you schedule.

LifecycleCopy Anchor Link

Pausing deletes the scheduled actions, the pending conditions and the pending manual tasks: they are created again when the campaign restarts and contacts reach those steps. Delete a campaign is irreversible; the lists and contacts stay.

Edit a campaign that already sentCopy Anchor Link

1. Pause it: POST /advanced/campaigns/{campaignId}/pause.
2. Read it: GET /advanced/campaigns/{campaignId}. The tree is in campaign.steps.
3. Change what you need in the tree you read, and keep the _id of every existing step and version. History, statistics per version and the position of each contact in the sequence are attached to those ids: new ids make contacts receive steps again.
4. Add new steps without _id.
5. Send the whole tree back, then start the campaign again.

Follow the campaignCopy Anchor Link

The statistics are computed on demand and cached. An unknown campaign answers 401 there, not 400: check the id before you check the key.

Manual tasksCopy Anchor Link

A TASK step waits for a human, for example a phone call. List what is waiting, then close each task with ok (done, event TASK_COMPLETED) or ko (failed, event TASK_FAILED). A condition on TASK_COMPLETED can route each case.

curl -X POST "https://api.emelia.io/advanced/campaigns/$CAMPAIGN_ID/manual-tasks/status" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId": "6650f1a2b839d80011c5d001", "taskId": "6650f1a2b839d80011c5c010", "status": "ok"}'

taskId is the _id of the TASK step. A task can be completed once.

Legacy campaignsCopy Anchor Link

The /emails/... and /linkedin/... campaign routes belong to the previous campaign system, where a campaign was email only or LinkedIn only. They still work and are documented under Legacy, but every new integration should use the routes on this page.