List delivery events for a message

Returns the delivery-event timeline for one outbound send, newest first — the delivery, bounce, and complaint events observed after the message was accepted for delivery.

Endpoint

GET https://api.dairo.app/v1/messages/{messageId}/events

Returns the delivery-event timeline for one outbound send, newest first — the delivery, bounce, and complaint events observed after the message was accepted for delivery. Each event carries its type, the recipient, occurredAt, and the send's subject/from/to; a bounce adds bounceType, bounceSubType, bounceAction, bounceStatus, and diagnosticCode, and a complaint adds complaintFeedbackType, complaintSubType, and complaintUserAgent. limit defaults to 50 and is capped at 100; this list is not cursor-paginated. The same signals arrive live as the message.delivered, message.bounced, and message.complained webhook events. Requires the messages:read scope; see outbound tracking.

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

Request

cURL

curl "https://api.dairo.app/v1/messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/events" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Path parameters

Name	Type	Required	Description
`messageId`	string	yes	The message's ID.

Query parameters

Name	Type	Required	Description
`limit`	integer	no	Maximum number of items in the page. (minimum 1, maximum 100, default `25`)

Response

200 Success. Body: application/json, OutboundEventListResponse.

Field	Type	Required
`object`	`"list"`	yes
`data`	array of OutboundEvent	yes
`pagination`	Pagination	yes

200

{
  "object": "list",
  "data": [
    {
      "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "providerMessageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "string",
      "recipient": null,
      "occurredAt": null,
      "subject": "Hello from Acme",
      "from": null,
      "to": [
        "string"
      ],
      "status": null,
      "bounceType": null,
      "bounceSubType": null,
      "bounceAction": null,
      "bounceStatus": null,
      "diagnosticCode": null,
      "complaintFeedbackType": null,
      "complaintUserAgent": null,
      "complaintSubType": null,
      "agentHint": null
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Errors

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

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).