UtilitayDevelopers
Get an API key
API reference

Sends

/sends

A send is one message written for an audience — a group, one contact, or everyone linked to one subject — the same send a person writes on the compose screen. It takes two calls: a draft is only written down, and nothing goes until you publish it. Through the API a send is plain text, by SMS and by email: WhatsApp only carries wording Meta has approved outside its 24-hour reply window, so plain text never goes that way. Recording an event is the other way messages are made, by your rules.

POST/sends/draftsCreate a draft · nothing is sentGET/sends/{send_id}Read · status and totalsPATCH/sends/{send_id}Edit · only while unsentshown →GET/sends/{send_id}/previewPreview · who and how manyGET/sendsList · ?status ?group_id ?contact_idPOST/sends/{send_id}/publishPublish · the call that sendsPOST/sends/{send_id}/voidCall off · before or while it goes

PATCHEdit an unsent send

Requires sends:write. Send only what changes. A draft, or a queued send waiting for its time, can be edited; once it is going, what was sent cannot be rewritten. A key edits only the drafts it wrote itself. Naming a new audience clears the old one. "" on email_mode or email_subject goes back to the default. scheduled_at: null takes a draft's time away; a queued send keeps one, so give it a new time or call it off.

Path parameters
send_iduuid · required
The send id.
Body parameters
group_iduuid · optional
contact_iduuid · optional
subject_iduuid · optional
bodystring · optional
priority_classnormal | critical | bulk · optional
email_modeoff | also | instead | only · optional
email_subjectstring · optional · max 200
scheduled_atdatetime · optional
A new time must be ahead of now.
copy_contact_idsuuid[] · optional
Returns

200 with the send. 400 when nothing changes, not_plain_sms for characters outside the SMS alphabet, or too_many_parts, with parts and limit, for new text longer than the instance sends; 409 once it is sending, done or called off.

Response body

One send: the same fields in every pack. Press Response on the sample to see one whole.

FieldTypeDescription
iduuidWhat /publish, /preview and GET /messages?send_id= name.
tenant_iduuidThe instance.
group_iduuid | nullIts audience, when that is a group.
contact_iduuid | nullIts audience, when that is one contact.
rule_iduuid | nullSet on a send a rule made. null on one written by hand or by a key.
event_iduuid | nullThe event that made it, for a rule's send.
template_iduuid | nullWording, on a send a rule or a person made. Always null on one a key writes: the API sends plain text.
bodystring | nullThe plain text.
variablesobjectValues for wording's placeholders. Empty on a plain-text send.
priority_classurgent | critical | normal | bulkA key writes normal, critical or bulk.
channel_policycontact_pref | whatsapp_only | sms_only | whatsapp_then_smsAlways sms_only on a send a key writes.
wa_connection_iduuid | nullThe sender it goes from. null is the default.
sms_connection_iduuid | null
email_modeoff | also | instead | only | nullThe email lane. null follows the organisation's setting.
email_connection_iduuid | null
email_subjectstring | nullnull goes out as “A message from” and the organisation's name.
created_byuuid | nullThe key's id, for a send a key wrote.
created_by_namestring | null“API key · ” and the key's name.
scheduled_atdatetime | nullWhen it goes. null is when it is published.
schedule_versioninteger
enqueued_versioninteger | null
enqueued_atdatetime | null
statusdraft | queued | sending | done | cancelledA draft sends nothing. Only a draft can be published.
last_errorstring | nullWhy it came back a draft, e.g. when Account would not cover it; or the reason it was called off.
hold_iduuid | nullThe budget reservation it went under.
batch_keystring | null
totalsobjectOnce it has gone: messages, sent, delivered, failed, cancelled, in_flight, and sms, email and sms_parts by channel.
subject_iduuid | nullIts audience, when that is one subject: every linked contact hears it.
copy_contact_idsuuid[] | nullWho gets a copy.
created_atdatetime
updated_atdatetime
eta_secondsinteger | nullOn a publish that queued: about how long until it has gone.

On failure the body is { error, code } instead.

Previous← Authentication, keys and scopesNextEvent types →