Campaigns

A campaign sends one message to every contact on one or more lists. It ties the lists, the content and the sender together so you can schedule, start, pause and measure them as one. To send to one person, see Sending basics or Email.

type Sends
rvm Ringless voicemail
sms Text, or RCS with rcs_content
email Email
voice_broadcast A call that plays one message to a person and another to a machine
ai_broadcast Calls handled by one of your AI agents

Starting a campaign is not delivery. Each contact's result arrives on the status webhook for the channel: contact.rvm.status, contact.sms.status or contact.email.status. Calling hours, the contact frequency limit and retries are explained in Send lifecycle. What each reason_code means, and what to do about it, is in Outcomes and what to do.

Routes

Method Route Scope What it does
GET /campaign/public/campaigns campaigns:read List campaigns
POST /campaign/public/campaigns campaigns:write Create a campaign
GET /campaign/public/campaigns/{id} campaigns:read Get a campaign
PUT /campaign/public/campaigns/{id} campaigns:write Not supported; answers 501. See Update a campaign
DELETE /campaign/public/campaigns/{id} campaigns:write Delete a campaign
POST /campaign/public/campaigns/{id}/start campaigns:send Start or resume sending
POST /campaign/public/campaigns/{id}/pause campaigns:send Pause sending
GET /campaign/public/campaigns/{id}/stats campaigns:read Get delivery counts
GET /campaign/public/balance balance:read Get your balance

List campaigns

Field Type Required Description
skip integer No How many to skip
limit integer No How many to return
search_term string No Match on the campaign name
status string No not_started, active, paused, complete or insufficient_credit
type string No One of the types above
curl "https://api-v2.dropcowboy.com/campaign/public/campaigns?type=sms&status=active" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

Create a campaign

Send type and a campaign_data object. Always send type: without it, the channel is guessed from the fields in campaign_data.

curl -X POST https://api-v2.dropcowboy.com/campaign/public/campaigns \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rvm",
    "campaign_data": {
      "name": "Spring reminder",
      "list_ids": ["8f3e1a9c-2d4b-4e7a-9c1f-5b6a7c8d9e0f"],
      "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
      "brand_id": "2c9d4e1f-7a3b-4f6c-8d2e-9b1a5c7e3f40",
      "media_id": "1b7e3c9a-4d2f-4a8b-9e6c-7f2a1d5b3c80"
    }
  }'

A new campaign answers 201:

{
  "data": {
    "campaign_id": "a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b",
    "approved": true,
    "started": false
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

approved says whether the campaign passed compliance review. started is true only when you set method to immediate and the campaign was approved on creation: it begins sending right away. Otherwise, start it with Start a campaign.

A campaign's state is campaign_data.status: not_started after create, then active, paused, complete, or insufficient_credit when your balance ran out.

campaign_data fields

Field Type Used by Description
name string All Required. Campaign name
list_ids string[] All Required. Lists to send to. GET /contact/public/lists
phone_line_id string Voice, text Sender numbers and return-call routing. GET /phone/public/lines
brand_id string Voice, text Registered brand. GET /automation/public/brands
media_id string rvm Audio file. GET /media/public/media
tts_body, voice_id string rvm Text to speech, up to 1,200 characters, and its voice. GET /voice/public/voices
sms_body string sms The text
rcs_content object sms RCS card, usually copied from a template. GET /template/public/templates?type=rcs
media_on_speech, media_on_beep, tts_on_speech, tts_on_beep string voice_broadcast Messages for a person and for a machine. The full set is in Send a voice broadcast.
ai_agent object ai_broadcast { "agent_id": "..." }, an active agent. GET /agents/public/agents
email_subject, email_html, email_preheader string email Content
email_from string email Required. The sending address, from one of your mailboxes. GET /domain/public/mailboxes
email_from_name, email_reply_to string email Sender name and reply-to address
email_from_mailbox_id string email The mailbox email_from belongs to. It doesn't set the sender on its own; send email_from too
email_template_id string email Saved template. GET /template/public/templates?type=email
method string All immediate sends to the whole list once started, and is used when you leave method out. Send immediate explicitly to start the campaign on create when it's approved. drip spreads sends over time.
drip object method: drip The sending window. See Drip schedule
drip_at integer method: drip Earliest send, in Unix milliseconds. Defaults to the time you create the campaign

An email campaign:

{
  "type": "email",
  "campaign_data": {
    "name": "Spring newsletter",
    "list_ids": ["8f3e1a9c-2d4b-4e7a-9c1f-5b6a7c8d9e0f"],
    "email_from_mailbox_id": "c5f1a8d3-6e2b-4c9f-b1a7-8d4e2c6f9b35",
    "email_from": "news@example.com",
    "email_from_name": "Example Dental",
    "email_subject": "Spring hours",
    "email_html": "<p>We are open Saturdays this spring.</p>"
  }
}

What a campaign must contain

Every campaign needs a name and at least one list in list_ids, plus the content for its type. Each media, voice and agent id has to be one you can use. A campaign missing any of these answers 400, and nothing is created.

type Content it needs
rvm media_id, or tts_body with voice_id
sms sms_body or rcs_content
email email_subject, email_html and email_from
voice_broadcast A message for a machine (media_on_beep or tts_on_beep) and one for a person (media_on_speech or tts_on_speech). Send the same message in both if you only have one. voice_id when either is text to speech
ai_broadcast ai_agent.agent_id

Some fields override type, in this order: sms_body or rcs_content makes it a text campaign, email_subject or email_html an email campaign, and ai_agent an AI broadcast. Otherwise the campaign is checked as the type you send.

The 400 names the field and a code in details:

{
  "type": "https://api-v2.dropcowboy.com/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "A ringless voicemail campaign needs a recording (media_id) or a text-to-speech script (tts_body and voice_id)",
  "instance": "/campaign/public/campaigns",
  "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24",
  "details": { "code": "CAMPAIGN_CONTENT_REQUIRED", "field": "media_id" }
}
details.code Cause
CAMPAIGN_NAME_REQUIRED name is missing or blank
CAMPAIGN_LIST_REQUIRED list_ids is missing or empty
CAMPAIGN_CONTENT_REQUIRED The content for the campaign's type is missing; field names the first one
CAMPAIGN_VOICE_REQUIRED The message is text to speech but there's no voice_id
CAMPAIGN_TTS_TOO_LONG A text-to-speech script is over 1,200 characters
CAMPAIGN_AGENT_REQUIRED An ai_broadcast has no ai_agent.agent_id
CAMPAIGN_SENDER_REQUIRED An email campaign has no email_from
CAMPAIGN_MEDIA_NOT_FOUND A media id isn't on your account, or was deleted
CAMPAIGN_VOICE_NOT_FOUND voice_id isn't one of your voices or a library voice
CAMPAIGN_AGENT_NOT_FOUND The agent isn't on your account, was deleted, is still a draft, or is turned off

Other fields we don't recognize are saved without an error, so a misspelled optional field is ignored. Read the campaign back after you create it.

Attestation

Creating a campaign through the API attests, under the API terms you accepted for your key or app, that it follows the rules, regulations and laws that apply, our Terms of Service, and the TCPA and TSR. We record which key or app created it and from what IP address. You don't send attestation fields; a compliance object in campaign_data is replaced with that record.

Drip schedule

A drip campaign sends only inside its window, at up to rate messages an hour. Contacts are still held to their own calling hours.

"drip": {
  "timezone": "America/Phoenix",
  "rate": 300,
  "monday":    { "enabled": true,  "start_time": "09:30", "end_time": "16:30" },
  "tuesday":   { "enabled": true,  "start_time": "09:30", "end_time": "16:30" },
  "wednesday": { "enabled": true,  "start_time": "09:30", "end_time": "16:30" },
  "thursday":  { "enabled": true,  "start_time": "09:30", "end_time": "16:30" },
  "friday":    { "enabled": true,  "start_time": "09:30", "end_time": "16:30" },
  "saturday":  { "enabled": false, "start_time": "09:30", "end_time": "16:30" },
  "sunday":    { "enabled": false, "start_time": "09:30", "end_time": "16:30" }
}
Field Type Required Description
timezone string Yes IANA time zone the window is read in, such as America/New_York
rate integer No Messages an hour. Default 60
monday to sunday object At least one enabled enabled, start_time and end_time for that day
start_time, end_time string Yes, on enabled days Wall-clock time as HH:mm, or an ISO 8601 timestamp of which only the time of day in timezone counts. An end_time of 00:00 means midnight

We store times as ISO 8601 timestamps, so a campaign you read back shows "2026-10-07T16:30:00.000Z" where you sent "09:30". Creating a drip campaign answers 400 when timezone isn't a valid IANA time zone, no day is enabled, or an enabled day's end_time isn't after its start_time.

Compliance review

A new campaign may need review by Drop Cowboy® before it can start. Until it is approved, approved is false and the campaign can't start. Create campaigns ahead of the time you need them.

A campaign with no content is never approved. You can't set risk or approved yourself; we ignore them on create.

Get a campaign

GET /campaign/public/campaigns/{id} returns the campaign with its campaign_data, approved, delivery_type and deliver_at. An unscheduled campaign has deliver_at 9007199254740991.

Update a campaign

The API doesn't update campaigns. PUT /campaign/public/campaigns/{id} answers 501:

{
  "type": "https://api-v2.dropcowboy.com/errors/not-implemented",
  "title": "Not Implemented",
  "status": 501,
  "detail": "Updating a campaign through the API isn't supported. Create a new campaign, or edit it in the dashboard.",
  "instance": "/campaign/public/campaigns/a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b",
  "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24"
}

To change one, delete it and create a new one, or edit it in the dashboard. To schedule when a campaign sends, create it with method: drip, a drip window and drip_at; see Drip schedule.

Delete a campaign

DELETE /campaign/public/campaigns/{id} deletes the campaign.

Start a campaign

POST /campaign/public/campaigns/{id}/start starts sending to the campaign's lists. On a paused campaign it resumes sending. A campaign still saved as a draft in the dashboard can't be started and returns 400.

{
  "data": { "campaign": { "campaign_id": "a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b" }, "started": true },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

started is false when nothing was queued. Starting a campaign that already finished returns it unchanged with started: true.

A campaign still waiting for compliance review doesn't start. You get 200 with approved: false and started: false, and the campaign stays in the review queue. Start it again once GET shows approved: true.

{
  "data": { "campaign_id": "a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b", "approved": false, "started": false },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

Pause a campaign

POST /campaign/public/campaigns/{id}/pause pauses sending. Messages already handed to the carrier can still arrive. Start the campaign again to resume.

Get campaign stats

GET /campaign/public/campaigns/{id}/stats returns delivery counts.

Field Type Required Description
start_ts integer No Count from this time, in epoch milliseconds
end_ts integer No Count up to this time, in epoch milliseconds
bucket_type string No Which roll-up to count from: 5min, hourly or daily (default). Finer roll-ups update sooner.
{
  "data": {
    "sent": 330,
    "delivered": 318,
    "failed": 12,
    "pending": 12,
    "read": 0,
    "billable": 318,
    "non_billable": 12,
    "delivery_rate": 0.9636,
    "failure_rate": 0.0364,
    "read_rate": 0
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

read comes only from RCS and some carriers, so treat read_rate as a minimum. Email campaigns also return opened, clicked, bounced, complained, unsubscribed, open_rate and click_rate. unsubscribed counts each contact once, however many of the campaign's emails or links they used.

Get your balance

GET /campaign/public/balance returns the one balance that pays for every channel. See Get your balance for the response. A contact who can't be sent to for lack of funds fails with 3000 (No Funds).

Delivery rules

Starting a campaign doesn't mean every contact gets the message. Each contact is checked as it's sent, under the same delivery rules as a single send: calling hours, the contact frequency limit, consent and the do-not-contact list. Each skipped contact gets its own reason_code; see Outcomes.

  • A texting campaign that reaches the daily limit carriers set for its registered texting campaign stops for the day. The contacts it hadn't reached yet get no result that day; the campaign switches to delivery_type: retry, with deliver_at at 9 a.m. Pacific the next day, and sends to them then. A campaign that had finished reopens to do this.
  • Email campaigns follow CAN-SPAM and the email frequency limit.
  • Test numbers and test email addresses on the Dialing rules page skip the frequency limits, so you can test a campaign on yourself more than once. Calling hours still apply to those test numbers unless you turn on Allow Test Numbers to Bypass TCPA Hours. See Test numbers.

Results

  • Each contact's result arrives on the channel's status webhook: contact.rvm.status for ringless voicemail, voice broadcasts and AI calls, contact.sms.status for texts, or contact.email.status.
  • The campaign sends campaign.started and campaign.completed.
  • AI calls also send one ai_agent.* event per call.

See Webhooks to subscribe.

Errors

Status Cause What to do
400 with a details.code The campaign is missing content, or names a media, voice or agent you can't use Fix the field in details.field; see What a campaign must contain.
400 You started a campaign that's still a draft Finish the campaign in the dashboard, then start it.
402 The account is past due Update billing; see Payment required.
403 with trial_feature_blocked Your brand isn't verified Verify your brand in the Trust Center, then retry.
403 A trial limit was reached, or the account is inactive Upgrade or reactivate the account.
404 The campaign id isn't on your account, or the campaign was deleted Check the id with GET /campaign/public/campaigns.
501 You sent PUT to update a campaign Create a new campaign, or edit it in the dashboard.

For everything else, see Responses, errors and limits.

Common problems

  • The campaign won't start. If start returned started: false with approved: false, the campaign is waiting for compliance review. Start it again once it's approved.
  • Create answered 400. Read details.code and details.field; the campaign is missing content or names an id you can't use.
  • Contacts were skipped. Read each contact's reason_code. Most skips are calling hours (4011), the contact frequency limit (4013), or missing consent.
  • The campaign stopped with insufficient_credit. Add funds, then start it again.

For more symptoms and fixes, see Troubleshooting.


While Drop Cowboy provides tools to support compliance efforts, customers remain solely responsible for obtaining proper consent, maintaining opt-out lists, and complying with all federal and state telemarketing regulations. Consult with your legal counsel to ensure your specific use case and consent mechanisms comply with applicable laws.

This information is for educational purposes only and does not constitute legal advice. Regulations vary by jurisdiction and use case. Always consult with qualified legal counsel to ensure your specific practices comply with applicable federal and state laws.

Code samples

The requests from this page, ready to copy. Set DC_KEY and DC_SECRET to your API key pair first.

List campaigns
curl "https://api-v2.dropcowboy.com/campaign/public/campaigns?type=sms&status=active" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Create a campaign
curl -X POST https://api-v2.dropcowboy.com/campaign/public/campaigns \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rvm",
    "campaign_data": {
      "name": "Spring reminder",
      "list_ids": ["8f3e1a9c-2d4b-4e7a-9c1f-5b6a7c8d9e0f"],
      "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
      "brand_id": "2c9d4e1f-7a3b-4f6c-8d2e-9b1a5c7e3f40",
      "media_id": "1b7e3c9a-4d2f-4a8b-9e6c-7f2a1d5b3c80"
    }
  }'
Create an email campaign
curl -X POST https://api-v2.dropcowboy.com/campaign/public/campaigns \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "campaign_data": {
      "name": "Spring newsletter",
      "list_ids": ["8f3e1a9c-2d4b-4e7a-9c1f-5b6a7c8d9e0f"],
      "email_from_mailbox_id": "c5f1a8d3-6e2b-4c9f-b1a7-8d4e2c6f9b35",
      "email_from": "news@example.com",
      "email_from_name": "Example Dental",
      "email_subject": "Spring hours",
      "email_html": "<p>We are open Saturdays this spring.</p>"
    }
  }'