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 unsentGET/sends/{send_id}/previewPreview · who and how manyGET/sendsList · ?status ?group_id ?contact_idPOST/sends/{send_id}/publishPublish · the call that sendsshown →POST/sends/{send_id}/voidCall off · before or while it goes

POSTPublish a send

Requires sends:write. Sends it — the only call that does, and it spends the instance's budget. With no scheduled_at it goes now: a small send in this request, a large one queued, with eta_seconds saying about how long. With one, it goes then. Only a draft can be published, so a retried publish is a 409, never a second send.

Path parameters
send_iduuid · required
The send id.
Returns

200 with the send: done or sending when it went now, queued when a queue or a time holds it, or draft with last_error when Account would not cover it. When the package and the organisation's wallet are used up and it stops at zero, last_error is “the package and the wallet are used up, so nothing went out; top up the wallet in Account” — a top-up in Utilitay Account is what helps, then publish the same draft again. Any other last_error names what to change. 409 when it is not a draft, when it was written by a person or another key — a key publishes only its own drafts — or when its audience is 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 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 →