# Send your first campaign

> Create a campaign, test it on your own phone, launch it and watch every recipient.

Send one message to a short list of recipients from a Number in your project,
then follow each recipient until the campaign completes.

> **Note**
>
> **Before you begin**
>
> - A project with at least one connected Number on the **Pro** tier. Campaigns
>   send only from Numbers whose [Number tier](https://docs.polymorfa.com/billing/number-tiers) includes
>   Campaigns; Free and Standard Numbers can save drafts but cannot launch.
> - For the API path, a project token with `campaigns:read` and
>   `campaigns:manage`. See [API keys](https://docs.polymorfa.com/development/api-keys).
> - Recipients who expect your message. A recipient who has never written to the
>   sending Number is held by default; see
>   [Recipients who never wrote first are held](https://docs.polymorfa.com/campaigns/safety-checks#recipients-who-never-wrote-first-are-held).

## Try it on test numbers

You can run this quickstart without a real phone when your test numbers are on
a tier that includes Campaigns.

| Rule | Value |
| --- | --- |
| Test numbers per project | 5 active, or 50 with the Simulation add-on |
| Who a test number can reach | Other connected test numbers in the same project only |
| Message types | Composed messages, A/B tests and drip steps send. Weighted message variations do not send from test numbers |

Create two test numbers in the project, send from one and use the other as the
recipient. See [Test numbers](https://docs.polymorfa.com/testing/test-numbers).

## Create the campaign

**Console:**

1. Open **Campaigns** in your project and select **New campaign**.
2. On **Type**, choose **Broadcast**.
3. On **Audience**, paste the recipients' phone numbers with their country
   codes, one per line. The import summary shows the numbers kept, duplicates
   and invalid rows.
4. On **Compose**, write the message. Use `{{first_name | there}}` to insert a
   recipient field with a fallback.
5. On **Sending**, select the Pro Number that sends the campaign and keep the
   **Steady** delay preset.
6. On **Schedule**, choose **Send on launch**.

Wait for **Draft saved** before you continue.

**API:**

Create a draft with the recipients and one composed message. A project token
names its own project, so the request needs no `projectId`.

```bash
curl -X POST "https://api.polymorfa.com/platform/campaigns" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First campaign",
    "recipients": [
      { "phone": "+14155550100", "variables": { "first_name": "Ada" } },
      { "phone": "+442071838750", "variables": { "first_name": "Alan" } }
    ],
    "messagesArray": [
      { "version": 2, "source": "Hi {{first_name | there}}, your order is ready to collect." }
    ],
    "senderConfig": {
      "sessionIds": ["'"$SESSION_ID"'"],
      "throughput": { "ratePerMinute": 12, "jitterMinMs": 800, "jitterMaxMs": 10000 }
    }
  }'
```

Save `data.id` from the response as `CAMPAIGN_ID`. `senderConfig.sessionIds`
pins the Number that sends; `$SESSION_ID` is its ID. The throughput values
match the Console's **Steady** preset.

## Send a test

A test sends one copy of the draft to your own phone through the same checks
as the launched campaign. It does not count as a recipient. The seed phone must
be a Number connected to your team, in any project.

**Console:**

On **Review**, select **Send test**. Choose the **Sending number**, enter the
**Seed recipient** phone number in international format and send the test.
Leave **Sample values** blank to use the first recipient's values.

**API:**

```bash
curl -X POST "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/test-send" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-campaign-test-1" \
  -d '{ "sessionId": "'"$SESSION_ID"'", "to": "+14155550199", "variables": { "first_name": "Ada" } }'
```

A `200` response with `status` `sent` means the test was sent. If the seed has
never written to the sending Number, the test returns `409 bansafe_cold_held`:
send any message from the seed phone to the sending Number, then test again.

## Launch

**Console:**

On **Review**, check the recipient count and the sending Number, then select
**Launch campaign**.

**API:**

```bash
curl -X POST "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/launch" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-campaign-launch-1" \
  -d '{}'
```

The response returns the campaign `status` and the `operationId` of its
delivery run. A launch that fails a check sends nothing:

| Status and code | What to do |
| --- | --- |
| `402 campaigns_not_entitled` | Move the sending Number to Pro, or pin a Pro Number |
| `400 invalid_parameter` on `senderConfig.sessionIds` | Reconnect the Number, or pin Numbers of one sending type |
| `422 campaign_variables_missing` | Add a fallback, or launch with `"skipMissingVariables": true` |
| `409 campaign_approval_required` | An owner or admin approves the launch in the Console |

## Follow the send

**Console:**

The campaign page shows delivery progress, then each recipient's status in the
**Recipients** panel. The campaign reaches **Completed** when every recipient
has resolved.

**API:**

```bash
curl "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/analytics" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"
```

`sentCount`, `deliveredCount`, `readCount`, `failedCount` and `skippedCount`
rise as recipients resolve. List each recipient's `status` and
`failureReason` with `GET /platform/campaigns/{campaignId}/recipients`, or
subscribe a webhook to `campaign.completed` to learn when the campaign ends.

A recipient with `failureReason` `cold_held` never wrote to the sending Number.
Ask them to message you first, or see
[Campaign safety checks](https://docs.polymorfa.com/campaigns/safety-checks) before you allow cold sends.

## What you built

Your campaign sent a paced message from a Pro Number, skipped anyone on your
team's opt-out list and reported every recipient's result.

## Next steps

- **[Send a campaign](https://docs.polymorfa.com/campaigns/send)**
Use templates, several messages, send windows, schedules and approvals.

- **[Build an audience](https://docs.polymorfa.com/campaigns/audiences)**
Keep a reusable list of recipients and their variables.

- **[How campaigns work](https://docs.polymorfa.com/campaigns/how-campaigns-work)**
Learn the statuses, checks and events behind each send.

- **[Opt-outs and STOP replies](https://docs.polymorfa.com/campaigns/opt-outs)**
Capture STOP replies and keep your suppression list current.
