Quickstart

This page takes you from no key to a message on your own phone, and the result of that send in your hands. It takes about ten minutes.

Prefer to start from code? Clone the Drop Cowboy® repo on GitHub and run examples/api/quickstart: one file, Node.js 20 or newer, nothing to install. It sends a ringless voicemail to your own number and tells you where to read the result. The same repo has the examples in Node.js, Python and C# and a Starter CRM built on Building Blocks.

1. Create an API key

In the dashboard, go to Developers > API keys and create a key. Copy the secret now, because it's shown once. Your account must be verified before you can create a key.

Put both values in environment variables. Every example in these docs uses them:

export DC_KEY="7f3c9a1e-5b2d-4e8f-a6c4-9d1b3e7f5a20"
export DC_SECRET="c8e2a4f6-1d3b-4a9c-8e7f-2b5d9a1c6e34"

Authentication covers scopes, OAuth and managing keys with the API.

2. Make your first call

Fetch your account to check the key works:

curl https://api-v2.dropcowboy.com/register/public/account \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
  "data": {
    "team_id": "4e9a2c7f-1b5d-4f3e-8c6a-9d2b7e4f1a53",
    "owner": {
      "user_id": "auth0|65f1c2d3e4a5b6c7d8e9f0a1",
      "first_name": "Jordan",
      "last_name": "Rivera",
      "email": "jordan@example.com"
    },
    "delivery_limits": {
      "frequency": { "max_attempts": 3, "window_days": 3, "window_ms": 259200000, "source": "default" }
    }
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

A 401 means the key or secret is wrong. Every response has this data and meta shape. See Responses, errors and limits.

If you'd rather click than type, import the Postman collection and send the same request from Postman. See OpenAPI and Postman.

3. Subscribe to results

A send answers 202 before anything is sent, and its result arrives later on a webhook. Create one before you send. Use any public HTTPS address where you can read incoming requests, and list the result events you want in event_types:

curl -X POST https://api-v2.dropcowboy.com/register/public/webhooks \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "hook_url": "https://hooks.example.com/dropcowboy", "event_types": ["contact.rvm.status", "contact.sms.status", "contact.email.status"] }'
Event type Results of
contact.rvm.status Ringless voicemail, voice broadcasts and AI calls
contact.sms.status Texts
contact.email.status Email

Webhooks are signed and retried, and one webhook covers every send. The response includes a signing_secret. Store it, and use it to check that deliveries came from Drop Cowboy. Add name to label the webhook, and create more webhooks if you want separate URLs or secrets. To change a webhook's URL or events later, update it. See Verify the signature.

Send routes also accept a callback_url, for when each send needs its own address. You don't need one here. See callback_url.

4. Send to yourself

First, add your own phone number and email address on the Dialing rules page in the dashboard, as a test number and a test email address. Test numbers skip the contact frequency limit, so you can send to yourself as often as you like while you build. Calling hours still apply unless you turn on Allow Test Numbers to Bypass TCPA Hours on that page. To test a specific result, such as a busy line or a do-not-contact failure, send to a simulated number instead.

A phone send needs a phone line to send from, and a ringless voicemail needs an audio file. Look up their ids:

curl https://api-v2.dropcowboy.com/phone/public/lines \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

curl "https://api-v2.dropcowboy.com/media/public/media?limit=10" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

Send a ringless voicemail

Ringless voicemail delivers your recorded message directly to the contact's voicemail box.

curl -X POST https://api-v2.dropcowboy.com/rvm \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "media_id": "1b7e3c9a-4d2f-4a8b-9e6c-7f2a1d5b3c80",
    "foreign_id": "quickstart-1"
  }'
{ "status": "queued", "message_id": "8e4a2c6f-9d1b-4f7e-b3a5-6c9e1f4d2b78" }

202 means the send was queued, not delivered. The result arrives on your contact.rvm.status webhook. See Ringless voicemail for every option, including spoken text instead of a file.

Send a text

The phone line must have an approved texting campaign.

curl -X POST https://api-v2.dropcowboy.com/sms \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "body": "Hello from the Drop Cowboy quickstart. Reply STOP to opt out.",
    "foreign_id": "quickstart-2"
  }'

See Texts for pictures, templates and replies.

Send a voice broadcast

A voice broadcast calls the contact and plays a message, one for a person and one for an answering machine. Pick a voice from GET /voice/public/voices.

curl -X POST https://api-v2.dropcowboy.com/voice-broadcast \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "voice_id": "9c4e7a2f-1b8d-4f3e-a6c5-2d9b4e7f1a63",
    "tts_on_speech": "Hi, this is a test call from the Drop Cowboy quickstart.",
    "tts_on_beep": "Hi, this is a test message from the Drop Cowboy quickstart.",
    "foreign_id": "quickstart-3"
  }'

See Voice calls for key presses, transfers and AI calls.

Send an email

Email goes out from a sending mailbox on a verified domain. Find yours with GET /domain/public/mailboxes.

curl -X POST https://api-v2.dropcowboy.com/email/public/email \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "address": "jordan@example.com", "name": "Jordan Rivera" }],
    "mailbox_id": "c5f1a8d3-6e2b-4c9f-b1a7-8d4e2c6f9b35",
    "subject": "Hello from the quickstart",
    "html": "<p>Hi Jordan, this is a test email.</p>"
  }'
{
  "data": { "success": true },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

Unlike the phone sends, email answers once it's handed off. success: false means nothing was sent. See Email.

5. Read the result

The result of a phone send arrives on your webhook like this:

{
  "event_id": "d1f3a8e2-7c4b-4f9a-9d22-9c1e2f3a4b5c",
  "event": "contact.rvm.status",
  "event_at": 1774041600000,
  "data": {
    "contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "drop_id": "6ae22fc9b41d3e0a7c5f9e21",
    "campaign_type": "rvm",
    "status": "success",
    "reason": "",
    "reason_code": 0,
    "to": "+13125550142",
    "from": "+12125550100",
    "foreign_id": "quickstart-1"
  }
}
  • status is success or failure.
  • reason_code says why. Outcomes lists every code and whether to retry.
  • Match results to your requests with foreign_id.

To check a send from the dashboard, search its message_id in Settings > API Logs. Status is whether it passed the checks made when it arrived; Delivery is the later result. The same sends are under Campaigns in the API entry (Show API send history is on by default). Add a status webhook so each result is also pushed to your server.

6. If nothing arrives

Work through Troubleshooting. The usual causes are:

  • Your webhook URL isn't publicly reachable over HTTPS, or doesn't answer POST with 2xx.
  • The key or secret on the send was wrong. That result (3007) never fires a webhook. It arrives on the send's callback_url, and Settings > API Logs lists the refused send when the key is yours.
  • The send was outside calling hours, so a voice send is held for later and a text fails with 4011. A held voice send has no webhook until it goes out. To drop to your own phone after hours, turn on Allow Test Numbers to Bypass TCPA Hours on the Dialing rules page. See Test numbers.
  • The phone line has no approved texting campaign, so a text fails with 3029.
  • Your balance is empty, so the send fails with 3000. Check it with GET /campaign/public/balance.

Find the IDs you need

Every id a send asks for comes from a lookup route. Fetch them once and store them.

You need Route Field
A phone line to send from GET /phone/public/lines phone_line_id
An audio file GET /media/public/media media_id
A voice, including your clones GET /voice/public/voices voice_id
A contact GET /contact/public/contacts contact_id
A contact list GET /contact/public/lists list_ids
A registered brand GET /automation/public/brands brand_id
An AI agent GET /agents/public/agents agent_id
A sending mailbox GET /domain/public/mailboxes mailbox_id
A saved template GET /template/public/templates template_id

Next steps

Follow a full guide

Each guide takes one task from setup to the result, with code in curl, Node.js, Python and C#. Start with Send a ringless voicemail on a retail plan, or browse every guide on the API reference.

Send to a whole list

A campaign sends to every contact on one or more lists in a single request. See Campaigns.

Place an AI call

An AI call puts one of your published AI agents on the phone with the contact. See Send an AI call.

Answer your phone with an AI agent

An AI receptionist is an agent that answers one of your phone lines. See Receptionist.

Go live

Before you send to real contacts, read Send lifecycle: what a 202 means, how to retry without sending twice, and the rules every send is checked against.


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.

1. Create an API key
export DC_KEY="7f3c9a1e-5b2d-4e8f-a6c4-9d1b3e7f5a20"
export DC_SECRET="c8e2a4f6-1d3b-4a9c-8e7f-2b5d9a1c6e34"
2. Make your first call
curl https://api-v2.dropcowboy.com/register/public/account \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
3. Subscribe to results
curl -X POST https://api-v2.dropcowboy.com/register/public/webhooks \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "hook_url": "https://hooks.example.com/dropcowboy", "event_types": ["contact.rvm.status", "contact.sms.status", "contact.email.status"] }'
4. Send to yourself
curl https://api-v2.dropcowboy.com/phone/public/lines \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

curl "https://api-v2.dropcowboy.com/media/public/media?limit=10" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Send a ringless voicemail
curl -X POST https://api-v2.dropcowboy.com/rvm \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "media_id": "1b7e3c9a-4d2f-4a8b-9e6c-7f2a1d5b3c80",
    "foreign_id": "quickstart-1"
  }'
Send a text
curl -X POST https://api-v2.dropcowboy.com/sms \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "body": "Hello from the Drop Cowboy quickstart. Reply STOP to opt out.",
    "foreign_id": "quickstart-2"
  }'
Send a voice broadcast
curl -X POST https://api-v2.dropcowboy.com/voice-broadcast \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "voice_id": "9c4e7a2f-1b8d-4f3e-a6c5-2d9b4e7f1a63",
    "tts_on_speech": "Hi, this is a test call from the Drop Cowboy quickstart.",
    "tts_on_beep": "Hi, this is a test message from the Drop Cowboy quickstart.",
    "foreign_id": "quickstart-3"
  }'
Send an email
curl -X POST https://api-v2.dropcowboy.com/email/public/email \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "address": "jordan@example.com", "name": "Jordan Rivera" }],
    "mailbox_id": "c5f1a8d3-6e2b-4c9f-b1a7-8d4e2c6f9b35",
    "subject": "Hello from the quickstart",
    "html": "<p>Hi Jordan, this is a test email.</p>"
  }'