Skip to Content
Alienmail Docs

Sync leads

Add, update, stop and remove the people a campaign emails.

A campaign emails its leads. This guide shows how to keep a campaign's leads in step with your CRM or product: add people when they qualify, update their details, and stop or remove them when things change.

Leads are identified by email address. You never need to store an Alienmail id for a person.

Find the campaign

Every call names a campaign by its id. Get it from List campaigns, or from the campaign's URL in Alienmail.

curl "https://app.alienmail.io/api/v1/campaigns?search=outreach" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"

Add people

Add leads takes 1 to 500 people per call.

curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/leads" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "email": "ada@example.com",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "jobTitle": "Head of Engineering",
        "company": "Analytical Engines",
        "custom": { "plan": "pro", "renewal_date": "2027-01-04" }
      },
      { "email": "grace@example.com", "firstName": "Grace" }
    ]
  }'

What happens to a new lead depends on the campaign:

Campaign statusWhat happens
activeThe lead is active and their first email is queued at once.
draft or pausedThe lead is pending and starts when the campaign does.
completedThe campaign becomes active again. Refused with 409 if it has no connected mailbox or its end date has passed.
archivedRefused with 409.

Read the answer

{
  "received": 2,
  "added": 1,
  "reactivated": 0,
  "alreadyIn": 1,
  "skippedBounced": 0,
  "skippedUnsubscribed": 0,
  "invalid": [],
  "ignoredCustomKeys": []
}
FieldMeaning
addedNew leads of the campaign.
reactivatedPeople who were removed from the campaign earlier and are back. They continue with their next email.
alreadyInPeople already in the campaign. Their place in the sequence is kept; only their custom values are updated.
skippedBounced, skippedUnsubscribedPeople left out because their address bounced, or they unsubscribed, in your workspace. They can't be added back through the API.
invalidEntries that couldn't be added, each with index, email and reason. The other entries are still added.
ignoredCustomKeysCustom keys that couldn't become a custom column (see below).

The call is safe to repeat, so a sync job can simply send its whole segment again.

A person who is already a lead in your workspace, from another campaign or an import, keeps the profile fields stored there. Adding them again doesn't overwrite firstName, company and the rest. Use Update a lead to change them.

Custom values

custom holds your own values for a lead in this campaign. Use them in email text as {{key}}, for example {{plan}}.

  • A key that isn't a custom column of the campaign yet is added as one. It must start with a lower-case letter, use only lower-case letters, digits and underscores, be at most 40 characters, and not be a built-in variable such as first_name or company.
  • A campaign holds up to 50 custom columns. Keys that don't fit, or aren't valid, come back in ignoredCustomKeys.
  • Keys are lower-cased. Values are stored as text, up to 5,000 characters.

Update a lead

Update a lead changes only what you send. null or an empty string clears a field.

curl -X PATCH "https://app.alienmail.io/api/v1/campaigns/42/leads/ada%40example.com" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobTitle": "CTO", "custom": { "plan": "enterprise" } }'

Write the email in the path with @ as %40. In JavaScript, use encodeURIComponent(email).

Rules:

  • Fields and custom values can be edited while the campaign is draft or paused. In an active campaign they can be edited until the lead has been sent an email. After that the call returns 409: pause the campaign, make the edit, and start it again.
  • In custom, every key must already be a custom column of the campaign. An unknown key returns 400.
  • companyDomain must be a domain like acme.com, and linkedinUrl and linkedinCompanyUrl must be linkedin.com URLs.

Stop and resume emails

To stop emailing someone without removing them, set their status:

curl -X PATCH "https://app.alienmail.io/api/v1/campaigns/42/leads/ada%40example.com" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "stopped" }'

A stopped lead stays in the campaign and its lead list, and gets no more emails. Send { "status": "active" } to resume them with their next email.

Only active and pending leads can be stopped, and only stopped leads can be resumed. A lead who replied may already be stopped: with stop on reply turned on, Alienmail stops them itself.

Lead statuses

StatusMeaning
pendingWaiting for the campaign to start.
activeGetting the campaign's emails.
stoppedEmails stopped, by you or because they replied. Still in the campaign.
completedFinished the sequence: no more emails are due.
unsubscribedUsed the unsubscribe link.
bouncedTheir address bounced.
skippedNot emailed because the campaign skips leads that failed the email check. Goes back to active when the campaign stops skipping them or a new check passes. You can't set it.

Remove people

Remove a lead takes one email in the path. Remove leads takes up to 500 in the body:

curl -X DELETE "https://app.alienmail.io/api/v1/campaigns/42/leads" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["ada@example.com", "grace@example.com"] }'
{ "received": 2, "removed": 1, "notInCampaign": 1, "invalid": [] }

Removing cancels the emails that were waiting. The emails already sent stay in the campaign's statistics, and the person stays in your workspace's leads. Add them again later and they come back as reactivated.

Read leads back

List leads returns a campaign's leads with their status, fields and custom values. Filter with status, or look one person up with search:

curl "https://app.alienmail.io/api/v1/campaigns/42/leads?search=ada%40example.com" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"

search matches part of the email, first name, last name or company, so check the email of the results. See Pagination to read every lead.

On this page