Skip to content
Shortcut: /, ⌘K or Ctrl+K

Send your first campaign

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

View as Markdown

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.

RuleValue
Test numbers per project5 active, or 50 with the Simulation add-on
Who a test number can reachOther connected test numbers in the same project only
Message typesComposed 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

  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.

Shell
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

Shell
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

Shell
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 codeWhat to do
402 campaigns_not_entitledMove the sending Number to Pro, or pin a Pro Number
400 invalid_parameter on senderConfig.sessionIdsReconnect the Number, or pin Numbers of one sending type
422 campaign_variables_missingAdd a fallback, or launch with "skipMissingVariables": true
409 campaign_approval_requiredAn 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

Shell
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#