Send one or more messages

Sends a single message (returns 201) or a batch of up to 1000 messages (returns 202). Messages are enqueued for delivery. Workspaces whose sending is handled inline rather than queued accept at most 200 messages per batch and send them 10 at a time, so a full batch completes well inside the request budget; a larger batch on such a workspace is refused with 400 batch_too_large before anything is sent, and should be split. Each item may carry an idempotency_key so a retried batch can be regrouped freely: matching items replay their original id with deduplicated=true, conflicting items are rejected individually, and the response counts accepted and rejected items. Authenticating with a test API key (prefix beeptest) simulates the full send lifecycle without a provisioned number and without delivering or billing anything; reserved magic numbers select deterministic outcomes (see the Testing with test keys & magic numbers guide).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
uuid

Workspace reply destination for inbound replies.

uri

Per-send override URL for delivery-status callbacks for this send only. Callbacks are still signed with the workspace status callback secret (set via PUT /api/v1/notification-settings), so they remain verifiable. Omit this field to use the workspace status callback URL, which applies to every send. Callbacks are unsigned only if no workspace secret is configured.

string

E.164 sending number to use for every message in this request. Must be an active phone number in your workspace (an unknown number returns 400). Omit to use the workspace default sender. The resolved number is returned as phone_number_id on each ack.

messages
array of objects
required
length between 1 and 1000

One to 1000 messages to send.

messages*
Headers
uuid
required
string
length between 1 and 255

Optional workspace-scoped retry key. Repeating an identical request returns the original message IDs without sending again; reusing it with a different payload returns 409. Keys expire after 24 hours.

Responses

Language
Credentials
Bearer
API Key
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json