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.

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.

3. 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.

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"

Each send below includes a callback_url, which receives the result of that one send. Use any public HTTPS address where you can read incoming requests. In step 4 you subscribe to webhooks, which carry the results of every later send.

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",
    "callback_url": "https://hooks.example.com/dropcowboy/result"
  }'

{ "status": "queued", "message_id": "8e4a2c6f-9d1b-4f7e-b3a5-6c9e1f4d2b78" }

202 means the send was queued, not delivered. The result arrives on your callback_url. 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",
    "callback_url": "https://hooks.example.com/dropcowboy/result"
  }'

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",
    "callback_url": "https://hooks.example.com/dropcowboy/result"
  }'

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.

4. Subscribe to results

Webhooks are signed and retried, so rely on them in production. Subscribe one URL to the result event for each channel. Make one call per event type:

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_type": "contact.rvm.status", "hook_url": "https://hooks.example.com/dropcowboy" }'

Each response includes a signing_secret. Store it, and use it to check that deliveries came from Drop Cowboy®. See Verify the signature.

5. Read the result

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

{
  "drop_id": "b3e7a1c9-8d5f-4b2e-9a6c-1f4d7b3e8a52",
  "contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "phone_number": "+13125550142",
  "product_code": "rvm",
  "status": "success",
  "reason": "",
  "reason_code": 0,
  "foreign_id": "quickstart-1",
  "attempt_date": "2026-03-20T15:15:00.000Z"
}

The webhook carries the same result in data, plus the event type:

{
  "event_id": "d1f3a8e2-7c4b-4f9a-9d22-9c1e2f3a4b5c",
  "event": "contact.rvm.status",
  "event_at": 1774041600000,
  "data": {
    "contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "drop_id": "b3e7a1c9-8d5f-4b2e-9a6c-1f4d7b3e8a52",
    "campaign_type": "rvm",
    "status": "success",
    "reason": "",
    "reason_code": 0,
    "to": "+13125550142",
    "from": "+12125550100"
  }
}

• 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 on the callback, and with drop_id or to on webhooks. Webhooks don't carry foreign_id.

6. If nothing arrives

Work through Troubleshooting. The usual causes are:

• The callback_url isn't publicly reachable over HTTPS.
• The send was outside calling hours, so a voice send is held for later and a text fails with 4011.
• 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.

Next steps

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.