UtilitayDevelopers
Get an API key
API reference

Sends

/sends

A send is one message written for an audience — a segment, one customer, or everyone subscribed to one subscription — 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 sentshown →GET/sends/{send_id}Read · status and totalsPATCH/sends/{send_id}Edit · only while unsentGET/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

POSTCreate a draft send

Requires sends:write. Writes the send down and sends nothing: it comes back with status draft. Preview it, then publish it. One audience: a segment, one customer, or one subscription. Several people are a kept segment — make one and fill it with POST /groups/{group_id}/members. A retired segment, an inactive customer or a member of staff is refused now rather than reaching nobody later; a temporary list is a 409. Unknown keys are refused with 400, among them template_id, channel_policy and the connection ids: the API sends plain text by SMS, from the instance's default sender.

Body parameters
group_iduuid · one of three
A kept segment, from GET /groups.
contact_iduuid · one of three
One customer.
subject_iduuid · one of three
One subscription: every customer subscribed to them hears it.
bodystring · required
The plain text, in the SMS alphabet: curly quotes, long dashes, emoji and letters with accents the alphabet lacks are refused while the instance keeps SMS to plain characters, its default (code not_plain_sms, with the characters in strays). Over 160 characters it goes as more than one SMS part: the preview says how many. Where the instance allows other characters, a text with one goes 70 characters a part. How many parts a text may be is the instance's setting, 3 unless it was raised, at most 10, counted as the SMS will go (on the cleaned text while SMS is kept plain); a longer text is refused with code too_many_parts, the parts it would be and the limit.
priority_classnormal | critical | bulk · default normal
urgent is not offered: it spends the emergency headroom past the budget, which is an owner's or an admin's to spend.
email_modeoff | also | instead | only · optional
The email lane. also: an email beside the SMS. instead: email for those with an address, SMS for the rest. only: email alone. Left out, the organisation's setting.
email_subjectstring · optional · max 200
Left out, “A message from” and the organisation's name.
scheduled_atdatetime · optional
When it goes, once published. Left out, it goes when published.
copy_contact_idsuuid[] · optional
Who gets a copy. Left out, the standing copy list under Settings.
Returns

201 with the send, status draft. 400 for a missing audience, more than one, or an unknown key; not_plain_sms for characters outside the SMS alphabet; too_many_parts, with parts and limit, for a text longer than the instance sends; 404 for an audience not on file; 409 for a temporary list.

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 customer.
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 subscription: every linked customer 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 →