# Quickstart (/quickstart)

<Steps>
<Step>
### Create an API key [#create-an-api-key]

In Alienmail, open **Workspace settings → Integrations** and find **API keys**. Enter a key name (like "CRM sync"), pick the **Write Access Key** [role](/authentication#roles-and-permissions) so the key can add leads, and create the key.

The key is shown **only once**, so copy it now and keep it in your server's secrets. The examples below read it from an environment variable:

```bash
export ALIENMAIL_API_KEY="paste your key here"
```

<Callout type="warn">
Use API keys only from your servers. Never put them in a web page, a mobile app or a public repository.
</Callout>
</Step>

<Step>
### Make your first request [#make-your-first-request]

List your campaigns, newest first.

<Tabs items={["curl","JavaScript","Python"]}>
<Tab value="curl">
```bash
curl "https://app.alienmail.io/api/v1/campaigns?limit=5" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"
```
</Tab>

<Tab value="JavaScript">
```js
const res = await fetch('https://app.alienmail.io/api/v1/campaigns?limit=5', {
  headers: { Authorization: `Bearer ${process.env.ALIENMAIL_API_KEY}` },
});
const { data, nextCursor } = await res.json();
```
</Tab>

<Tab value="Python">
```python
import os, requests

res = requests.get(
    "https://app.alienmail.io/api/v1/campaigns",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {os.environ['ALIENMAIL_API_KEY']}"},
)
print(res.json())
```
</Tab>
</Tabs>

You get a page of campaigns:

```json
{
  "data": [
    {
      "id": 42,
      "name": "Q1 outreach",
      "status": "active",
      "leadCount": 180,
      "sentCount": 412,
      "lastSentAt": "2026-11-13T09:30:00.000Z",
      "createdAt": "2026-11-02T08:15:00.000Z",
      "updatedAt": "2026-11-13T09:30:00.000Z"
    }
  ],
  "nextCursor": null
}
```

Note the `id` of the campaign you want to work with. It is also the number in the campaign's URL in Alienmail.
</Step>

<Step>
### Add a lead to a campaign [#add-a-lead-to-a-campaign]

Send people by email address. Replace `42` with your campaign id.

```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",
        "company": "Analytical Engines",
        "custom": { "plan": "pro" }
      }
    ]
  }'
```

The answer says what happened to each person:

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

Calling it again with the same person is safe: they are counted in `alreadyIn` and not added twice. See [Sync leads](/guides/sync-leads) for the full rules.
</Step>

<Step>
### Stop emailing someone [#stop-emailing-someone]

When a lead becomes a customer, stop their emails. The lead is addressed by email, with `@` written as `%40`.

```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" }'
```
</Step>

<Step>
### Try any endpoint in the browser [#try-any-endpoint-in-the-browser]

Every page of the [API reference](/api-reference) has a playground. Paste your key in **Authorization**, fill in the fields and press **Send** to see the real response.

<Callout type="info">
The playground calls the live API with your key, so writes are real. Use a test campaign while you explore.
</Callout>
</Step>
</Steps>

## Next steps [#next-steps]

<Cards>
<Card title="Authentication" href="/authentication">
Roles, permissions and key errors.
</Card>

<Card title="Campaigns and mailboxes" href="/guides/campaigns-and-mailboxes">
Start and pause campaigns, and manage mailboxes.
</Card>
</Cards>