API reference

Sends

/sends

A send is one message written for an audience — a class, one parent, or everyone linked to one student — 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 sent GET/sends/{send_id}Read · status and totals PATCH/sends/{send_id}Edit · only while unsent GET/sends/{send_id}/previewPreview · who and how many GET/sendsList · ?status ?group_id ?contact_id POST/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 parent.

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 student: every linked parent 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 scopes NextEvent types →