messages

Send one message

Send one WhatsApp template, SMS, or email message to a contact, or create the contact in the same call with to.create: true.

Business-initiated WhatsApp messages (outside the 24-hour customer-service window) must use an approved template; within 24 hours of the customer's last message a free-form body is accepted instead of template_id.

Pass business_id for managed-business scoping; pass channel_id when you need to send from a specific WhatsApp number.

If channel_id is omitted for a WhatsApp template, Blueticked uses the number attached to that approved template.

Use Idempotency-Key on write calls to avoid duplicate sends.

The recipient is looked up in your contacts; one that is not there answers 404 not_found with details.reason: "recipient_not_found". Pass to.create: true (optionally with to.first_name and to.last_name) to create the contact in the same call, exactly as POST /api/v1/contacts would: in the business you name, or your default business. It needs the contacts:write scope too. The answer says contact_created, and carries contact_id when the send created the contact or the key holds contacts:read.

A contact created by a send triggers your contact-created automations and the contact.created webhook, like any new contact. It has given no consent, so a marketing send with to.create is refused up front (details.reason: "consent_required") and nothing is written; record the opt-in with POST /api/v1/contacts first. The contact is created only after every other check passes (the channel, the body, the wallet, the plan's contact limit, which answers 403 plan_limit_reached), so a refused send leaves none behind; if the send fails after it (the send queue unavailable, say), the contact stays.

Authorize WhatsApp sends with either messages:send or the least-privilege whatsapp:send scope.

Send a customer statement (template with PDF): Send a WhatsApp template that has a DOCUMENT header, attaching a per-recipient PDF by URL.

Send a template with a personalised link button: Send a WhatsApp template whose URL button ends in {{1}}, supplying the per-send link ending.

Send an SMS: Send a plain-text SMS to a contact (or create it with to.create: true), from a free-form body or a saved message template.

Send an email: Send a transactional email to a contact (or create it with to.create: true), with an optional subject line and reply-to.

Send a marketing email (HTML body): Send a marketing email with your own HTML body, rendered inside the branded shell with the required compliance footer.

Validate one message: Validate auth, contact lookup, channel readiness, template variables and opt-outs without sending.

post/api/v1/messages

Request

  • Base URL: https://app.blueticked.com
  • URL: https://app.blueticked.com/api/v1/messages
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A unique key (e.g. a UUID) that makes a POST safe to retry: replaying the same key within 24h returns the original result instead of acting twice.

Request body

business_idstring uuid nullable
channel'whatsapp' | 'sms' | 'email' required
channel_idstring uuid nullable
bodystring
subjectstring
template_idstring uuid
template_variablesobject
test_modeboolean
message_type'transactional' | 'marketing'
htmlstring
ccstring[]
bccstring[]
reply_tostring

Response

Validated without queueing: returned when the request body sets test_mode:true. No provider send, no billing. A blu_test_ key on its own does NOT produce this: a sandbox key follows the normal path and returns 202 with status:"queued", simulating delivery from there. Set test_mode:true when you want the request validated and echoed back instead of queued.

test_modetrue required
status'validated' required
channel'whatsapp' | 'sms' | 'email' required
business_idstring uuid nullable required
tostring required
contact_idstring uuid nullable required
would_create_contactboolean required
channel_idstring uuid nullable required
template_idstring uuid nullable required
template_namestring nullable required
rendered_body_previewstring required
would_enqueueboolean required
request_idstring required

Example response

{
  "channel": "whatsapp",
  "business_id": "22222222-2222-4222-9222-222222222222",
  "to": "+27800000001",
  "contact_id": "ff506e53-e2f0-4d92-884a-dab77d628bad",
  "channel_id": "11111111-1111-4111-9111-111111111111",
  "template_id": "1f2f3f4f-0000-4000-9000-abcdef123456",
  "template_name": "order_update",
  "rendered_body_preview": "Hi Sam, your order #1001 is on the way.",
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

Changes

No recorded changes to this operation across all 1 revision of this API.