> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first campaign, end to end

> From a description of who you want to their replies in your inbox: every call in order, and what each one costs.

This guide runs one small outbound from start to finish. You find 20 people, get their work emails, write them a two-step email sequence, launch it and read who replied. Each step links to the guide that covers it in full.

> [!NOTE]
>
> You need an API key that can write (see [Authentication](https://docs.outbound.dev/authentication.md)) and one mailbox to send from. The whole run costs about \$1.42 at most: \$0.02 for the search, up to \$0.40 for the emails found, and \$1 for the mailbox's first 30 days. Everything else here is free.

**1. Find the people**

Describe who you want. The search turns the description into filters and answers with the people and those filters:

```bash theme={null}
curl https://api.outbound.dev/v1/people/search \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "operations directors at logistics companies in Portugal", "limit": 20}'
```

```json theme={null}
{
  "data": [
    {
      "first_name": "Ana",
      "last_name": "Ruiz",
      "job_title": "Director of Operations",
      "job_company_name": "Halden Freight",
      "job_company_website": "haldenfreight.com",
      "linkedin_url": "linkedin.com/in/ana-ruiz-ops"
    }
  ],
  "filters": { "job_title_levels": ["director"], "job_title_role": ["operations"], "job_company_location_country": ["portugal"] }
}
```

A search costs \$0.001 for each person it returns, so this page costs \$0.02 at most. The `X-Charged-Usd` header on the answer says what it cost. Check `unresolvedCriteria` in the answer: when it is not empty, part of your description could not be turned into a filter and the search is broader than you meant. See [Find people](https://docs.outbound.dev/guides/find-people.md).

> [!TIP]
>
> To know how big the whole audience is before you pay for any of it, send the same `filters` to `POST /v1/people/count`. Counting is free.

**2. Put them in a list**

A campaign writes to lists, so make one:

```bash theme={null}
curl https://api.outbound.dev/v1/lists \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Portugal freight ops"}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e20", "name": "Portugal freight ops", "type": "people", "rowCount": 0, "createdAt": "2026-11-14T10:05:00.000Z" }
```

Then add the people the search found, as rows. Copy each person's fields across:

| From the search | To the row |
| - | - |
| `first_name`, `last_name` | `firstName`, `lastName` |
| `linkedin_url` | `linkedinUrl`, as a full link: put `https://www.` in front |
| `job_title` | `jobTitle` |
| `job_company_name` | `companyName` |
| `job_company_website` | `companyDomain` |

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/rows \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows": [{"firstName": "Ana", "lastName": "Ruiz", "linkedinUrl": "https://www.linkedin.com/in/ana-ruiz-ops", "jobTitle": "Director of Operations", "companyName": "Halden Freight", "companyDomain": "haldenfreight.com"}]}'
```

A call takes up to 500 rows, and lists are free. Send it once: every row becomes a new person, so the same call sent twice adds everyone twice. See [Build lists](https://docs.outbound.dev/guides/build-lists.md).

**3. Find their work emails**

Enrich the list. `maxSpendUsd` refuses the job before it starts if it could cost more than you allow:

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/enrich \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"find": "email", "maxSpendUsd": 1}'
```

It answers `202` with a job. Read the job until its `status` is no longer `running`, no faster than every 15 seconds:

```bash theme={null}
curl https://api.outbound.dev/v1/jobs/6a1f0c2b9d4e8a7f3c5b2e14 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

A work email costs \$0.02 when one is found, and nothing when none is. The job's `chargedUsd` says what the run cost, and the emails are now on the list's rows. See [Enrich people](https://docs.outbound.dev/guides/enrich-people.md).

**4. Connect a mailbox**

A campaign sends from a mailbox of your own. If `GET /v1/accounts` shows none yet, connect one: see [Connect sending accounts](https://docs.outbound.dev/guides/connect-sending-accounts.md). A mailbox costs \$1 for each 30 days it stays connected.

**5. Create the campaign and write its emails**

A new campaign is a draft. It sends nothing until you launch it:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Portugal freight ops", "listIds": ["6a1f0c2b9d4e8a7f3c5b2e20"], "timezone": "Europe/Lisbon"}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e30", "status": "initializing" }
```

It starts with one empty email step. Find its id with `GET /v1/campaigns/{campaignId}/steps`, then write it. The subject and body go together, and the variables in braces are filled in for each person:

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps/6a1f0c2b9d4e8a7f3c5b2e31 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Your Lisbon fleet", "body": "<p>Hi {Contact First Name},</p><p>Saw {Contact Company} runs trucks out of Lisbon. Worth a short call?</p><p>{Sender Signature}</p>"}'
```

Add a follow-up that goes out three days after the first email:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/steps \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "email", "sequenceNumber": 1, "daysBetween": 3, "subject": "Re: your Lisbon fleet", "body": "<p>Hi {Contact First Name}, is a short call this week worth it?</p><p>{Sender Signature}</p>"}'
```

See [Run campaigns](https://docs.outbound.dev/guides/run-campaigns.md) for LinkedIn steps, A/B splits and steps written by AI.

**6. Check it is ready**

Ask whether the campaign would start now, without starting it:

```bash theme={null}
curl https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/readiness \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "ready": true, "people": { "total": 20, "withEmail": 14, "withoutEmail": 6, "withLinkedin": 20 } }
```

When `ready` is false, `reason` names what is missing, such as `no_active_email_accounts`. `people` shows who the campaign can reach: an email-only campaign skips the people without an email.

**7. Launch**

```bash theme={null}
curl -X POST https://api.outbound.dev/v1/campaigns/6a1f0c2b9d4e8a7f3c5b2e30/launch \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e30", "status": "active" }
```

This is the only call that makes the campaign send. Emails go out between 9:00 and 17:00 in the campaign's time zone, Monday to Friday, at five and thirty-five minutes past each hour. Sending is free.

**8. Read the replies**

Replies land in the inbox of the mailbox that sent the email. List the campaign's conversations, newest first:

```bash theme={null}
curl "https://api.outbound.dev/v1/conversations?channel=email&campaignId=6a1f0c2b9d4e8a7f3c5b2e30" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

Each conversation carries its last message, so one call shows who answered and what they said. The inbox is free, to read and to answer from. See [Work the inbox](https://docs.outbound.dev/guides/work-the-inbox.md).

## What the run cost

| Step | Price | This run |
| - | - | - |
| Searching 20 people | \$0.001 a person returned | \$0.02 |
| Work emails | \$0.02 for each one found | Up to \$0.40 |
| The mailbox | \$1 for each 30 days connected | \$1.00 |
| Lists, the campaign, sending and the inbox | Free | \$0.00 |

`GET /v1/usage` shows the same spend by day and by product. See [Track your spend](https://docs.outbound.dev/guides/track-spend.md) and [Pricing and billing](https://docs.outbound.dev/billing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.