Send message
POST/api/v1/messages
One message to one recipient, made from the template's latest published version and the data. Sent at once.
The data is checked against the template's data contract before anything is sent. The message keeps the template version and the HTML's SHA-256, so what was sent can always be shown again.
idempotency_key is unique per workspace: the same key again answers 200 with the first message and sends nothing new, so a retry never becomes a duplicate. The same key with other content gives 409 idempotency_conflict.
A message that may not go – the address is blocked for its class, or the month's allowance is used up – is kept with the status suppressed and a reason, and the receipt message.suppressed is sent. The answer is still 201.
Scope
messages:sendSend messages – the person behind the key must be all members.
Body
JSON, Content-Type: application/json. Unknown fields return 422.
templatestringrequired- The template's key. The message is made from the template's latest published version.
toobjectrequiredto.emailstringrequired- The recipient's address.at most 254 characters
to.namestring | null- The recipient's name. Fills {{first_name}} and {{last_name}} in the template.at most 200 characters
categorystringrequired- service: reminders and letters within the engagement – stopped by a bounce, a spam complaint, erasure and a manual block, never by an unsubscribe, and has no unsubscribe link. marketing: planning and knowledge letters – follows the workspace's usual rules, unsubscribes and the monthly cap.
servicemarketing dataobject<optional>required- The message's data, ready to show (amounts formatted, dates written out). Checked against the template's data contract.
idempotency_keystringrequired- Unique per workspace and message, e.g. the mailing's id in Qrona. The same key again gives the same message, never a new one.at least 1 characters · at most 255 characters
referencestringrequired- Qrona's reference. Comes back in every receipt (webhook).at least 1 characters · at most 255 characters
client_refstringrequired- The firm's client, pseudonymously. The number of different clients per month is the basis of the invoice.at least 1 characters · at most 255 characters
reply_tostring | null- The reply address for this message, e.g. the client's consultant. Without: the add-on's.at most 320 characters
Retrying a request
Feel free to send the Idempotency-Key header (e.g. a UUID). If the same request is sent again with the same key within 24 hours, the first response is returned, without anything being done twice. Batch and idempotency
Response
201 The message (200 when idempotency_key has already been used with the same content).
message_idstringrequired- The message's id.
statusstringrequired- queued: waiting for another attempt · sent: handed to the sending service · delivered: delivered · bounced: bounced · complained: spam complaint · failed: could not be delivered · suppressed: not sent, see reason.
queuedsendingsentdeliveredbouncedcomplainedfailedsuppressed reasonstring | nullrequired- Why a message was not sent: bounced, complained, manual, erased, unsubscribed (marketing only), service_limit, monthly_cap or payment.
templatestringrequiredtemplate_versionintegerrequired- The template version the message was made from. Published versions never change.
html_sha256stringrequired- SHA-256 of the HTML the recipient got.
categorystringrequiredservicemarketingreferencestringrequiredclient_refstringrequiredcreated_atstring (time, ISO 8601)required- When the message was received.