Send a message from a Dairo inbox

POST https://api.dairo.app/v1/messages

Sends one message from the inbox named by inboxId to the addresses in to (plus optional cc/bcc, up to 50 recipients total); the inbox's own channel decides the transport — email, Telegram, or Slack. Provide exactly one body source — text, html, react, or a stored template — or send attachment-only (or a Telegram-only payload); zero or more than one body source is a 400. An immediate send delivers synchronously and returns the definitive status (sent with a providerMessageId, or failed), while a send with a future sendAt (RFC3339, at most 30 days out) returns status: scheduled after passing every gate. Set the Idempotency-Key header (or the body field idempotencyKey, ≤128 characters) so a retried send returns the original result instead of delivering twice. Inline base64 attachments are capped at 8 MiB each and 8 MiB per send across at most 10 files; attach a stored object by objectId to send up to 24 MiB. A delivered send emits the message.sent webhook event and is metered for billing per recipient (to + cc + bcc); it requires the messages:send scope, and sending email shows the full request shape. Set dryRun: true to validate a send without performing it: the request is checked exactly as a real send would be and a non-persisted preview (status: "preview") comes back, with nothing created, queued, sent, metered, or billed. Test mode is scoped to the REQUEST, not to the credential — a dairo_test_ API key still sends real, billable mail.

Scope: messages:send. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/messages" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "to": "person@example.com",
    "subject": "Welcome to Acme",
    "text": "Thanks for signing up."
  }'

Headers

Body

Required, application/json: SendMessageRequest.

Response

200 Success. Body: application/json, SendMessageResponse.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "sent",
  "providerMessageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "error": null,
  "warnings": [
    {
      "recipient": "person@example.com",
      "reason": "complaint",
      "message": "Recipient previously complained; do not contact again unless you are sure.",
      "sourceMessageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "providerMessageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "complaintFeedbackType": null,
      "complaintUserAgent": null,
      "lastEventAt": "2026-10-19T09:30:00Z"
    }
  ],
  "channel": "email",
  "channelMetadata": {},
  "scheduledAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.