Skip to Content
Alienmail Docs
Leads

Add leads

POST
/campaigns/{id}/leads

Adds up to 500 people to a campaign by email. In an active campaign a new lead's first email is queued at once; in a draft or paused one they wait as pending until it starts. Adding to a completed campaign makes it active again.

The call is safe to repeat: someone already in the campaign is counted in alreadyIn and only their custom values are updated. A person who is already a lead in your workspace keeps the fields stored there; change them with Update a lead. People whose address bounced or who unsubscribed in your workspace are left out and counted.

An entry with an invalid email is reported in invalid and the others are still added, so check it. It is refused with 409 when the campaign is archived, or completed with no connected mailbox or a past end date.

Requires the LEAD_CAMPAIGN_ENROLL permission.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key of your workspace, from Workspace settings, Integrations. Each key has a role, and the role decides which endpoints it may call.

Path Parameters

id*integer

The campaign id: the number in the campaign URL in Alienmail, or id from the campaign list. An id that is not a campaign of your workspace returns 404.

Request Body

application/json
  1. body
leads*array<>

1 to 500 people. When an email appears twice, the first entry is used.

Items1 <= items <= 500

Response Body

What happened to the people in the request.

application/json
  1. response
received*integer

Entries in the request.

added*integer

People who are now new leads of the campaign.

reactivated*integer

People who were removed from the campaign earlier and are back in it.

alreadyIn*integer

People who were already in the campaign. Only their custom values were updated.

skippedBounced*integer

People left out because their address bounced in your workspace.

skippedUnsubscribed*integer

People left out because they unsubscribed in your workspace.

invalid*array<>

Entries that could not be added, with the reason.

ignoredCustomKeys*array<string>

Custom keys that could not become a custom column.

Example Request
curl -X POST 'https://app.alienmail.io/api/v1/campaigns/42/leads' \  -H 'Content-Type: application/json' \  -d '{  "leads": [    {      "email": "ada@example.com"    }  ]}'
Example Response
{  "received": 2,  "added": 2,  "reactivated": 0,  "alreadyIn": 0,  "skippedBounced": 0,  "skippedUnsubscribed": 0,  "invalid": [],  "ignoredCustomKeys": []}