Dairo Docs
GuidesAPI referenceDashboard
API referenceInboxes

List inboxes

Returns every inbox on your account as a list envelope — object: "list" with the inboxes in data, ordered newest first by createdAt.

Endpoint
GET https://api.dairo.app/v1/inboxes

Returns every inbox on your account as a list envelope — object: "list" with the inboxes in data, ordered newest first by createdAt. A key restricted to specific inboxes lists only the inboxes it is pinned to. This collection is not paginated: pagination.nextCursor is always null and pagination.hasMore is always false, so a single call returns all of them. Each entry carries the inbox id, address, localPart, domain, domainStatus (pending, verified, or failed), assigned agent, mode, status, channel, and lastMessageAt. Requires the inboxes:read scope.

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

Request

cURL
curl "https://api.dairo.app/v1/inboxes" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Response

200 Success. Body: application/json, InboxListResponse.

FieldTypeRequiredDescription
object"list"yes
dataarray of Inboxyes
paginationPaginationyes
200
{
  "object": "list",
  "data": [
    {
      "object": "inbox",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "address": "person@example.com",
      "localPart": "string",
      "domain": "yourapp.com",
      "domainStatus": "pending",
      "agent": "string",
      "mode": "receive_send",
      "status": "active",
      "createdAt": "2026-10-19T09:30:00Z",
      "lastMessageAt": "2026-10-19T09:30:00Z",
      "channel": "email"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Errors

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

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

Replay events from the ledger to webhooks

Re-reads a slice of the event ledger and re-delivers it to your webhook subscriptions, reconstructing each event body byte-identically — same eventId, type, and data — and signing it with a fresh X-Dairo-Timestamp like any delivery attempt, so it passes the consumer's verification and timestamp window while consumer-side dedupe on the event ID stays exact.

Create or return an inbox

Creates an inbox at username@domain and returns the created inbox object.

On this page

RequestResponseErrors