API reference / Outreach
Ringless voicemail
Adding ringless voicemail (voicemail drops) to your own product is what Drop
Cowboy is for. Send from your app with POST /rvm, or send a list with a
campaign of type: rvm. People sometimes call this white label. To put the
dialer, inbox or messenger in your product too, use Building Blocks.
POST /rvm delivers a voicemail directly to one person's voicemail box. The
recipient fields, foreign_id, callback_url and merge fields
work the same on every send; see Sending basics.
For a full walk-through that ends with the result, see Send a ringless voicemail on a retail plan. To have a voice speak your text, see Send a ringless voicemail with text to speech. To build on a retail account and go live on your own carrier with the same request body, see Test on retail, then go live on BYOC.
To send one from code you can run right now, clone the
Drop Cowboy® repo on GitHub. Its
quickstart is one Node.js file, and examples/api has the same send in
Node.js, Python and C#.
A
202means accepted, not delivered. The result of each voicemail arrives on thecontact.rvm.statuswebhook. 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.
Send a ringless voicemail
POST /rvm. With OAuth, the token needs the rvm:send scope. Give the audio
as exactly one of these:
| Field | Type | Required | Description |
|---|---|---|---|
media_id |
string | One audio option | The media_id from the upload or import response. Add files with a signed upload or from a URL, and list yours with GET /media/public/media. |
tts_body |
string | One audio option | Text to speak, up to 1,200 characters once merge fields are filled in. Needs voice_id. Supports merge fields. |
voice_id |
string | With tts_body |
The voice for tts_body. List voices with GET /voice/public/voices. |
audio_url |
string | One audio option | A public http(s) URL of an mp3 or wav file, up to 50 MB. We fetch it when the voicemail is sent. |
audio_url is available on BYOC plans only and must be enabled by support.
Contact support to enable it. If you're testing on a retail account before
connecting your carrier, support can enable it for testing; while testing,
voice sends go only to your test numbers. Otherwise, upload your file and send
media_id, or use text to speech. Without it, the send fails with 3014 (Not
allowed audio_url). A send to a number that isn't one of your test numbers
while testing fails with 3040 (Test Numbers Only).
Then choose the phone line and options:
| Field | Type | Required | Description |
|---|---|---|---|
phone_line_id |
string | No | The phone line the voicemail is sent from. The recipient sees one of its numbers, and return calls and texts reach that line, where its routing applies: forward, queue, voicemail or whatever you set up. Leave it out to send from your default phone line. List lines with GET /phone/public/lines. |
caller_id |
string | BYOC only | Your carrier's number in E.164, shown as the caller ID exactly as given. Only bring-your-own-carrier (BYOC) accounts can set it. On a retail account don't send it; it's ignored. If you send phone_line_id too, the line wins. |
byoc |
object | No | BYOC only. sti_orig_id (a UUID) and sti_attestation (A, B or C) set the STIR/SHAKEN details for the call. |
mobile_only |
boolean | No | Skip the send when the number isn't a mobile number. |
Every voicemail goes out from a phone line on your account unless you use
BYOC. On BYOC the send goes out on your connected carrier and needs no routing
field. Bring your own carrier shows the whole
flow, from connecting the carrier to sending from your own number with an
audio_url. Use your own numbers on BYOC covers each way
to bring numbers, with code, and
Receive calls on your own numbers
covers calls back. If you leave out phone_line_id and your account has no
default phone line, the send fails with 4010.
curl -X POST https://api-v2.dropcowboy.com/rvm \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Idempotency-Key: 6f1c2e9a-8b3d-4f7a-a2c5-9d4e1b7f3a60" \
-H "Content-Type: application/json" \
-d '{
"contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"phone_selector": "mobile_phone",
"phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
"voice_id": "7d2a9e4b-1c6f-4b3a-8e5d-2f9c7a1b4e63",
"tts_body": "Hi {{contact.first_name|there}}, your order is ready for pickup.",
"foreign_id": "order-1042",
"callback_url": "https://your-server.example.com/dropcowboy/rvm-result"
}'
The ids are placeholders. Use your own: contact_id from
GET /contact/public/contacts, phone_line_id (an ivr_id) from
GET /phone/public/lines, and voice_id from GET /voice/public/voices. With
an uploaded file, send the media_id from the upload or import response. A
media_id copied from these docs fails with 3001.
phone_line_id with one audio source is the most portable body: it works on
retail, and keeps working after you connect your own carrier and import your
numbers onto the same line. See
Test on retail, then go live on BYOC.
The route answers 202 with {"status": "queued", "message_id": "..."}. The
result comes later on the contact.rvm.status
webhook, and on your callback_url if the
send has one. Set foreign_id on the send to match the result to it. In the
dashboard, search the message_id on Settings > API Logs (Delivery column)
or open Campaigns, where API send history is shown by default. See
Where results arrive and
Receive the result of a send. Outside the contact's calling hours the voicemail is held and retried for up
to 3 days; see Calling hours. Every send is
also checked automatically against your do-not-contact list (4016)
and the contact frequency limit
(4013).
A reason_code of 0 means the voicemail was left in the contact's mailbox.
After that, the contact's carrier decides when it shows up: carriers can take
up to 24 hours to deliver it, and some filter it as spam. Neither is in our
control.
Proof of delivery
A voicemail result includes proof_of_delivery_url: a recording that shows
your message reached the contact's voicemail system, available for 7 days.
Results 0, 4001 and 4002 have it. On 4001 and 4002 the recording is
the carrier saying why the mailbox couldn't take the message.
Voice broadcasts and AI calls a voicemail system answered get proof of delivery too, on the same results. Proof of delivery explains how to play a link, get a new one, and keep the recording.
Common problems
- You got a
202("status": "queued") with amessage_id, but haven't received the voicemail. A202means the request was queued, not sent. Read the result on thecontact.rvm.statuswebhook or yourcallback_url, or in the dashboard: search themessage_idon Settings > API Logs (Delivery column) or open Campaigns (Show API send history is on by default). Common results while testing are4010(No Caller ID) and4013. See I got a 202 but nothing happened. If you are testing repeatedly to your own phone number, the 4th attempt in 3 days fails with4013(Too Many Attempts) unless you add your number under Test Numbers on the Dialing rules page (Every test send fails with 4013). Outside the recipient's calling hours, the voicemail is held until the window opens. - The send failed with
3014.audio_urlisn't enabled on your account, or the send gave no audio. Send amedia_id, ortts_bodywithvoice_id. On a BYOC plan, contact support to enableaudio_url. - The send failed with
3040. Your account is in testing mode and the number isn't one of your test numbers. Add it under test numbers on the Dialing rules page, or finish connecting your carrier. See Test on retail, then go live on BYOC. - The send failed with
3001. Themedia_idisn't on your account, for example one copied from these docs. Use themedia_idfrom your own upload or import. - The send failed with
3017or3018.byoc.sti_orig_idisn't a UUID, orbyoc.sti_attestationisn'tA,BorC. - The send failed with
3002or3015.3002meanstts_bodywas sent withoutvoice_id.3015meansvoice_idwas sent withouttts_body. Send both, or neither. - The voicemail failed with
4001or4002. Their mailbox can't take a message, so retrying won't help. Reach them on a channel they've agreed to; see Act on the result. - The proof of delivery link answers
not_ready. Wait forcontact.rvm.receipt, or retry afterRetry-After. See Proof of delivery. - The result is
0but the contact hasn't seen the voicemail. Carriers can take up to 24 hours to deliver it, or may filter it as spam. That's outside our control. - The send failed with
4010. It named nophone_line_idand your account has no default phone line. Passphone_line_id, or set a default line.
For more symptoms and fixes, see Troubleshooting. Every code is in Outcomes.
Ringless voicemail technology delivers messages directly to voicemail inboxes. Delivery success depends on carrier compatibility, device type, and recipient settings. While designed for voicemail delivery, technical factors may affect performance. Drop Cowboy does not guarantee delivery rates or specific outcomes.
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.