Send lifecycle

This page covers what happens after you send: what the response means, how to retry without sending twice, the rules every send is checked against, and where the result arrives. It applies to the four send routes, POST /rvm, POST /sms, POST /voice-broadcast and POST /ai-broadcast, and notes where email differs.

What a 202 means

A send route answers 202 as soon as it has your request. Your credentials, the recipient, the delivery rules and your balance are checked after that. The result arrives later on your signed webhooks, and on the send's callback_url if you set one.

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

Treat 202 as "received", not "sent". An invalid number or a missing media file still gets 202 and then fails. Wait for the result before you report a send as successful. Every send gets this same body, whatever happens to it afterwards.

The four send routes answer with this flat object, without the data / meta envelope used elsewhere. message_id is your receipt for the request. Search it in Settings > API Logs to see whether the send was accepted or refused, and what your callback_url answered (see Find a request). The result itself comes on your webhooks and callback_url, which don't carry message_id. Set a foreign_id on the send and match results on it. Where results arrive lists every place to read a result.

Only these responses come back on the request itself:

Status Body Meaning What to do
202 {"status":"queued","message_id":"..."} Received Wait for the result
400 Problem details, type ending validation-error The body is empty, isn't a JSON object, or is over 256 KB, or a header has characters that aren't printable ASCII Fix the request
401 Problem details, type ending missing-credentials No x-key / x-secret pair and no Authorization: Bearer token Add credentials
429 {"message":"Too Many Requests"} You're sending too fast Back off and retry. See Rate limits.
500 {"status":"error"} Nothing was received Retry with the same Idempotency-Key
502 Problem details, type ending internal-error The request may or may not have been received Retry with the same Idempotency-Key

Wrong credentials still get 202. A wrong key or secret, or a bearer token that is invalid, expired or lacks the route's send scope, fails the send with 3007 (Not authorized). No webhook fires for it, because the request can't be tied to your account. It arrives only on the send's callback_url. When the key exists but the secret or token is wrong, Settings > API Logs also lists the refused send. While you build, check there, or add a callback_url to your test sends. See Authentication for scopes.

A recipient that can't be resolved, such as a malformed number or a deleted contact, also gets 202 and then fails. See Choose a recipient.

Retry safely with Idempotency-Key

Send an Idempotency-Key header with every send so a retry can't send twice:

  1. Generate a new key for each new send. A random UUID works. Keys are 1 to 255 printable ASCII characters.
  2. If you don't know whether a request got through (a timeout, a network error, a 500 or 502), retry with the same key and the same body. Within 24 hours the retry is skipped if the first request was received, so the contact gets the message at most once.
  3. To send again on purpose, for example after fixing a failed send, use a new key.
curl -X POST https://api-v2.dropcowboy.com/sms \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f8c2e1a-7b3d-4a9e-8c6f-2d1e5b7a9c34" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "body": "Your order is ready for pickup. Reply STOP to opt out."
  }'

Keys are compared exactly as sent, per account. Key order and whitespace in the body don't affect the match, but the route does, so never reuse a key on a different route. If no result has arrived 15 minutes after a request, retry with the same key: the retry sends only if the first attempt stopped before sending.

When a retry is ignored or fails

Retry Send routes Email
Same key, same body 202. The retry is skipped: nothing is sent and no second callback or webhook fires. The first request's result is the one that counts. The first successful response, with Idempotent-Replayed: true. 409 idempotency-request-in-progress while the first request is still running.
Same key, different body or route 202, then the send fails with 3027 (Idempotency Key Conflict). Nothing is sent. 409 idempotency-key-reused
Invalid key 202, then the send fails with 3028 (Invalid Idempotency Key). Nothing is sent. 400 invalid-idempotency-key
Empty header Treated as no key Treated as no key

Email keeps a key only after a successful send, so a retry after an error or success: false sends again. Email has the details.

Delivery rules

Every send is checked against these rules after the 202. A send that breaks one fails with a reason_code; Outcomes says what each code means and whether to retry. Email has its own rules, described on Email.

Calling hours

Texts (SMS, MMS and RCS) sent outside the contact's allowed hours fail with 4011. They aren't retried, so resend inside the window. The window follows federal and state-specific calling hours in the contact's time zone.

Ringless voicemails, voice broadcasts and AI calls outside the window are held and tried again until the window opens. A voice send that still can't go out after 3 days fails. There is no webhook or callback_url result until the send goes out, or until it fails after 3 days.

Test numbers follow the same hours unless you turn on Allow Test Numbers to Bypass TCPA Hours on the Dialing rules page.

Contact frequency limit

Each account has a contact frequency limit: the most attempts to one phone number in a rolling window. The default is 3 attempts in 3 days. Campaign sends and dialer calls to the same number count together across your team. Test numbers are exempt.

A send over the limit fails with 4013 (Too Many Attempts). It isn't retried, so try again once the window has moved on.

Account owners change the limit on the Dialing rules page, for example to 7 attempts in 7 days for debt collection. The page accepts at least 3 attempts and a window of at least 3 days. Read the current value from GET /register/public/account (see Account):

{
  "delivery_limits": {
    "frequency": { "max_attempts": 3, "window_days": 3, "window_ms": 259200000, "source": "default" }
  }
}

source is team when your account has its own setting and default when it uses the platform default.

A send can make the limit stricter for itself, never looser:

Field Applied when Otherwise
max_attempts Lower than the account's attempts Ignored
max_attempt_window_ms Longer than the account's window. Over 30 days is capped at 30 days. Ignored

Values that aren't positive whole numbers are ignored without an error. A 4013 status webhook carries the limit that was applied and the attempts counted. Read it there, because the callback_url body doesn't include it:

"frequency_limit": { "max_attempts": 3, "window_days": 3, "attempts_in_window": 3 }

Your account's do-not-contact list and consent rules are checked automatically on every send at the moment of sending:

  • A number on your account's do-not-contact list is blocked automatically and fails with 4016 (Internal DNC). A listed email fails with 5014.
  • A number on the known-litigator block list (or flagged by your connected Blacklist Alliance / WebRecon / RND screening) is blocked automatically with 4017 or 4019.
  • Drop Cowboy® does not automatically scrub against the US National or state DNC registries. Import or add those numbers to your do-not-contact list (POST /dnc/public/dnc) or check them before sending.
  • When your account requires consent, a contact without consent for the channel fails with 6011. Record consent first; see Consent.
  • When your account requires double opt-in for texts, an unconfirmed contact gets a confirmation request first. Your text goes once they confirm. The text is held on the contact, so send it with contact_id rather than to. A text sent with to fails with 6011, and no request goes out.

Manage your account's list with Do-not-contact list and see Outcomes and Troubleshooting for every failure code.

Balance

Send routes never answer 402. An empty balance fails the send with 3000 (No Funds). Check it with GET /campaign/public/balance (see Account), then add funds or turn on auto-recharge. Routes that spend money while you wait answer 402 instead; see Payment required.

Test numbers

List your own phone numbers as test numbers on the Dialing rules page. They skip the contact frequency limit, so you can send to yourself repeatedly while you build. Calling hours still apply unless you also turn on Allow Test Numbers to Bypass TCPA Hours on that page. That setting is off by default. Listing the numbers is not enough. Use the bypass only for numbers you own. Test email addresses on the same page skip the email frequency cap.

While support has your account in testing mode, for example before you move to your own carrier, ringless voicemail and voice broadcast sends go only to your test numbers. A send to any other number fails with 3040. See Test on retail, then go live on BYOC.

Simulated numbers

To test how your code handles each result without reaching a real phone, send to a simulated number. Area code 555 isn't assigned to any phone, so nothing is dialed or texted. Send to it the way you send to any other number. The result arrives a few seconds later on your webhooks, and on the send's callback_url if it has one, like any other result.

Simulated sends are free. They ignore calling hours, and they have no recording, so they never carry a proof of delivery link. The result's from is a simulated number too, not one of yours.

Area code 555 numbers outside +1 555 000 to +1 555 003 are test numbers instead: a call to one is answered and a text gets a reply. See 555 test numbers.

Ringless voicemail:

Number Result
+15550010001 success, 0
+15550010002 failure, 4000 (VoiceMail Not Detected)
+15550010004 failure, 4005 (No Answer)
+15550010005 failure, 4006 (User Busy)
+15550010006 failure, 4004 (Number not reachable)
+15550010090 failure, 4016 (Internal DNC)
+15550010091 failure, 4017 (Known Litigator)
+15550010092 failure, 4019 (RND Reassigned)
+15550010093 failure, 4021 (RND Error)
+15550010094 failure, 6000 (Carrier Denied Use Case)
+15550010095 failure, 6002 (Pool Suspended)
+15550010097 failure, 4013 (Too Many Attempts)
+15550010098 failure, 6005 (Opt-in Revoked)
+15550010099 failure, 6011 (Opt-in Missing)

Texts:

Number Result
+15550020001 success, 0
+15550020003 failure, 4004 (Number not reachable)
+15550020005 failure, 4008 (Spam detected)
+15550020090 failure, 4016 (Internal DNC)
+15550020091 failure, 4017 (Known Litigator)
+15550020092 failure, 6000 (Carrier Denied Use Case)
+15550020093 failure, 6003 (Pool Not Ready)
+15550020095 failure, 4013 (Too Many Attempts)
+15550020096 failure, 6006 (Opt-in Pending)
+15550020097 failure, 6004 (Opt-in Flagged)
+15550020098 failure, 6011 (Opt-in Missing)
+15550020099 failure, 6001 (Carrier Suspension)

Where results arrive

Every send produces one result: success, or failure with a reason_code and reason. Receive it with a webhook:

  • Signed webhooks. The way to receive results. They're signed and retried, and one subscription covers every send. Create a webhook for the events you need; Results of your sends lists the event for each channel.
  • callback_url. Only for when each send needs its own address. One unsigned POST per send, described below.

A send with a callback_url still fires your webhooks, so the result arrives in both places. Handle a result arriving twice.

To check one send, call GET /register/public/api-logs?message_id=<message_id> with a key that has logs:read. The send's row has a delivery summary, and GET /register/public/api-logs/{log_id} adds each recipient's result. It's for looking a send up, not for polling every one.

Match a result to your send with the foreign_id you set on it. Status webhooks carry drop_id and foreign_id, but not message_id or log_id. Without a foreign_id, match on to and the time.

You can also read results in the dashboard. Open Campaigns (Show API send history is on by default), then open the API entry. It lists each send's number and result; hover a failed result for the reason, such as Too Many Attempts or No Caller ID. Settings > API Keys > View Send History opens the same entry. It's read-only. Search the message_id on Settings > API Logs: the Delivery column is the later result, and Status is whether the request was accepted.

When a send is tied to a contact, its result is also on the contact's timeline. Sends to a bare to number usually aren't, so don't rely on the timeline for API sends.

For working receivers for both channels, in Node.js, Python and C#, see Receive the result of a send.

When a voicemail system took the call, the result can also carry a link to a recording that proves delivery. That covers ringless voicemail, and voice broadcasts and AI calls left in a mailbox. It's available for 7 days; see Proof of delivery.

If no result arrives, work through I got a 202 but nothing happened.

callback_url

Use callback_url only when each send needs its own address, for example a URL that carries your own job ID. Otherwise register a webhook, which is signed, retried and set up once for every send.

Every send route accepts a callback_url. It gets one POST per send with the result, including early failures such as 3007 and 3027:

  • It isn't signed, and it's tried once with a 10-second timeout and no retry. If your server is down when the result arrives, the result is lost there.
  • It must be a publicly reachable http or https URL. A value that isn't a URL fails the send with 3019 (Invalid Callback). A URL on a private address is skipped without affecting the send.
  • Redirects aren't followed, so a 3xx answer is final.
  • It echoes your foreign_id, as status webhooks do.
  • Its log_id is the log_id of the send's row in Settings > API Logs. Each callback attempt, with what your server answered, is on that row. The row doesn't hold the result; the callback body does.
{
  "drop_id": "6ae22fc9b41d3e0a7c5f9e21",
  "contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "phone_number": "+13125550142",
  "caller_id": "+13125550100",
  "product_code": "sms",
  "status": "failure",
  "reason": "TCPA Hours",
  "reason_code": 4011,
  "foreign_id": "order-1042",
  "attempt_date": "2026-03-20T03:15:00.000Z"
}

The example is trimmed. The full body also carries team_id, session_id, log_id, quantity, the cost fields and dnc, and, for a result with proof of delivery, proof_of_delivery_url. A send whose recipient was looked up also carries network: the recipient's carrier (name, type, and mno / network_id when the registry tracks that carrier). A refusal before that lookup omits it. If you signed the call with a BYOC certificate you uploaded, the same body also carries sti_identity, sti_attestation, sti_orig_id and sip_call_id. They are additive, like proof_of_delivery_url. Retail JSON is unchanged. SMS callbacks never get them. Early failures (3007 / 3027) have no session identity, so they stay as they are. See Results of your sends for what the four fields mean.

A voicemail callback from a BYOC team also carries route_attempts and route_attempts_truncated: which of your carriers were tried and what each answered. They don't need a signed call. See Which carriers were tried.

A send that fails before anything is sent (bad credentials, an idempotency conflict, a validation error) has a different body. It has no drop_id, and phone_numbers lists the numbers the request named:

{
  "status": "failure",
  "reason": "Idempotency Key Conflict",
  "reason_code": 3027,
  "product_code": "sms",
  "team_id": "3f6c2a1e-8b4d-4c7a-9e2f-5a1b3c4d6e7f",
  "log_id": "6b2d9f4e-1a7c-4e3b-9d8f-2c5a7e1b4d93",
  "session_id": null,
  "contact_id": null,
  "phone_selector": null,
  "phone_number": "+13125550142",
  "phone_numbers": ["+13125550142"],
  "foreign_id": "order-1042",
  "attempt_date": "2026-03-20T03:15:00.000Z"
}

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.

Retry safely with Idempotency-Key
curl -X POST https://api-v2.dropcowboy.com/sms \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f8c2e1a-7b3d-4a9e-8c6f-2d1e5b7a9c34" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "body": "Your order is ready for pickup. Reply STOP to opt out."
  }'