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.
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.
Create the campaign#
Console
- Open Campaigns in your project and select New campaign.
- On Type, choose Broadcast.
- 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.
- On Compose, write the message. Use
{{first_name | there}}to insert a recipient field with a fallback. - On Sending, select the Pro Number that sends the campaign and keep the Steady delay preset.
- 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.
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
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
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
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 API List campaign 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 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#
Use templates, several messages, send windows, schedules and approvals.
Build an audienceKeep a reusable list of recipients and their variables.
How campaigns workLearn the statuses, checks and events behind each send.
Opt-outs and STOP repliesCapture STOP replies and keep your suppression list current.