# Sync leads (/guides/sync-leads)

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 [#find-the-campaign]

Every call names a campaign by its `id`. Get it from [List campaigns](/api-reference/campaigns/listCampaigns), or from the campaign's URL in Alienmail.

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

## Add people [#add-people]

[Add leads](/api-reference/leads/addLeads) takes 1 to 500 people per call.

```bash
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 status | What happens |
|---|---|
| `active` | The lead is `active` and their first email is queued at once. |
| `draft` or `paused` | The lead is `pending` and starts when the campaign does. |
| `completed` | The campaign becomes `active` again. Refused with `409` if it has no connected mailbox or its end date has passed. |
| `archived` | Refused with `409`. |

### Read the answer [#read-the-answer]

```json
{
  "received": 2,
  "added": 1,
  "reactivated": 0,
  "alreadyIn": 1,
  "skippedBounced": 0,
  "skippedUnsubscribed": 0,
  "invalid": [],
  "ignoredCustomKeys": []
}
```

| Field | Meaning |
|---|---|
| `added` | New leads of the campaign. |
| `reactivated` | People who were removed from the campaign earlier and are back. They continue with their next email. |
| `alreadyIn` | People already in the campaign. Their place in the sequence is kept; only their custom values are updated. |
| `skippedBounced`, `skippedUnsubscribed` | People left out because their address bounced, or they unsubscribed, in your workspace. They can't be added back through the API. |
| `invalid` | Entries that couldn't be added, each with `index`, `email` and `reason`. The other entries are still added. |
| `ignoredCustomKeys` | Custom 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.

<Callout type="info">
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](#update-a-lead) to change them.
</Callout>

### Custom values [#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]

[Update a lead](/api-reference/leads/updateLead) changes only what you send. `null` or an empty string clears a field.

```bash
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 [#stop-and-resume-emails]

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

```bash
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 [#lead-statuses]

| Status | Meaning |
|---|---|
| `pending` | Waiting for the campaign to start. |
| `active` | Getting the campaign's emails. |
| `stopped` | Emails stopped, by you or because they replied. Still in the campaign. |
| `completed` | Finished the sequence: no more emails are due. |
| `unsubscribed` | Used the unsubscribe link. |
| `bounced` | Their address bounced. |
| `skipped` | Not 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-people]

[Remove a lead](/api-reference/leads/removeLead) takes one email in the path. [Remove leads](/api-reference/leads/removeLeads) takes up to 500 in the body:

```bash
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"] }'
```

```json
{ "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 [#read-leads-back]

[List leads](/api-reference/leads/listLeads) returns a campaign's leads with their status, fields and custom values. Filter with `status`, or look one person up with `search`:

```bash
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](/pagination) to read every lead.