API reference / Track results
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:
- Generate a new key for each new send. A random UUID works. Keys are 1 to 255 printable ASCII characters.
- If you don't know whether a request got through (a timeout, a network
error, a
500or502), 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. - 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 | |
|---|---|---|
| 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 }
Consent and do-not-contact
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 with5014. - A number on the known-litigator block list (or flagged by your connected Blacklist Alliance / WebRecon / RND screening) is blocked automatically with
4017or4019. - 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_idrather thanto. A text sent withtofails with6011, 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 unsignedPOSTper 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
httporhttpsURL. A value that isn't a URL fails the send with3019(Invalid Callback). A URL on a private address is skipped without affecting the send. - Redirects aren't followed, so a
3xxanswer is final. - It echoes your
foreign_id, as status webhooks do. - Its
log_idis thelog_idof 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.