API reference / Outreach
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 |
|
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.statusorcontact.email.status. Calling hours, the contact frequency limit and retries are explained in Send lifecycle. What eachreason_codemeans, 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, withdeliver_atat 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.statusfor ringless voicemail, voice broadcasts and AI calls,contact.sms.statusfor texts, orcontact.email.status. - The campaign sends
campaign.startedandcampaign.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: falsewithapproved: false, the campaign is waiting for compliance review. Start it again once it's approved. - Create answered
400. Readdetails.codeanddetails.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.