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 202 means accepted, not delivered. The result of each voicemail arrives on the contact.rvm.status webhook. 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.

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 a message_id, but haven't received the voicemail. A 202 means the request was queued, not sent. Read the result on the contact.rvm.status webhook or your callback_url, or in the dashboard: search the message_id on Settings > API Logs (Delivery column) or open Campaigns (Show API send history is on by default). Common results while testing are 4010 (No Caller ID) and 4013. 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 with 4013 (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_url isn't enabled on your account, or the send gave no audio. Send a media_id, or tts_body with voice_id. On a BYOC plan, contact support to enable audio_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. The media_id isn't on your account, for example one copied from these docs. Use the media_id from your own upload or import.
  • The send failed with 3017 or 3018. byoc.sti_orig_id isn't a UUID, or byoc.sti_attestation isn't A, B or C.
  • The send failed with 3002 or 3015. 3002 means tts_body was sent without voice_id. 3015 means voice_id was sent without tts_body. Send both, or neither.
  • The voicemail failed with 4001 or 4002. 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 for contact.rvm.receipt, or retry after Retry-After. See Proof of delivery.
  • The result is 0 but 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 no phone_line_id and your account has no default phone line. Pass phone_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.

Code samples

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

Send a ringless voicemail
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"
  }'