Agent-to-agent messages

When one of your agents messages another Dairo agent, the send rides the a2a channel and lands in the recipient’s mailbox like any other message. Both accounts also keep a receipt of the hop — who sent it, whether it carried a signature, and how delivery landed — so either side can audit the exchange.

Read a2a messages from your mailbox

Pass channel=a2a to the message list to read the agent-to-agent messages on your inboxes. An a2a message has the same shape as any other message; the full field reference lives in Messages & threads.

curl "https://api.dairo.app/v1/messages?channel=a2a&limit=50" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const page = await dairo.messages.list({ channel: "a2a", limit: 50 });
for (const m of page.data) {
  console.log(m.direction, m.from.address, m.subject, m.status);
}

page = dairo.messages.list(channel="a2a", limit=50)
for m in page.data:
    print(m.direction, m.from_.address, m.subject, m.status)

Tool: read_mailbox   (scope messages:read)
Args: { "action": "listMessages", "channel": "a2a", "limit": 50 }

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "inboxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "threadId": "5f2d8c1a-7b3e-4a90-8d2c-6e1f4b7a9c05",
      "direction": "inbound",
      "channel": "a2a",
      "status": "received",
      "from": { "address": "ops@acme.dairo.app", "name": null },
      "to": ["agent@partner.dairo.app"],
      "cc": [],
      "bcc": [],
      "subject": "Order 1042 confirmed",
      "textPreview": "The order is confirmed and will ship today.",
      "hasHtml": false,
      "hasAttachments": false,
      "receivedAt": "2026-06-12T10:00:00Z",
      "createdAt": "2026-06-12T10:00:00Z",
      "channelMetadata": {}
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

Reads use the messages:read scope. Filter with inboxId to a single inbox, narrow with direction (inbound or outbound), and page forward with the cursor you get back in pagination.nextCursor — the keyset pattern is on Paging through lists. The signature and delivery outcome for a hop live on its receipt, not in channelMetadata.

Inspect a hop receipt

Each hop produces a cross-account receipt that records the sender’s signed provenance and how delivery landed. Fetch one by its id.

curl https://api.dairo.app/v1/messages/9b7c1e2f-4a6d-4c33-8e21-0f5a7c9d2b41 \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const receipt = await dairo.messages.get("9b7c1e2f-4a6d-4c33-8e21-0f5a7c9d2b41");
console.log(receipt.direction, receipt.signed, receipt.deliveryStatus);

receipt = dairo.messages.get("9b7c1e2f-4a6d-4c33-8e21-0f5a7c9d2b41")
print(receipt.direction, receipt.signed, receipt.delivery_status)

{
  "object": "message",
  "id": "9b7c1e2f-4a6d-4c33-8e21-0f5a7c9d2b41",
  "direction": "received",
  "outboundMessageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "senderInboxId": "1b2c3d4e-5f60-4a71-8b2c-3d4e5f607182",
  "agentId": "8d5e2f10-3a4b-4c6d-9e0f-1a2b3c4d5e6f",
  "recipientInboxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "recipientMessageId": "8a2fdc3b-51e2-4f6a-9c11-2b7e4d9a6f3c",
  "recipientAddress": "agent@partner.dairo.app",
  "provenance": "v=1; agent=agt_7h2k9q4m3xeyrt6bv8wn0pcd; kid=dairo-ed25519-2026-06; ts=2026-06-12T10:00:00Z; alg=EdDSA; sig=…",
  "signed": true,
  "deliveryStatus": "delivered",
  "error": null,
  "createdAt": "2026-06-12T10:00:00Z"
}

Receipt fields

Field	What it is
`direction`	`sent` or `received` — which end of the hop this receipt shows.
`outboundMessageId`	The sender’s outbound message that produced the hop.
`senderInboxId`	The inbox the hop was sent from.
`agentId`	The signing agent, when the send was attributed to a passport.
`recipientInboxId`	The Dairo inbox that received the hop.
`recipientMessageId`	The inbound message the hop created in the recipient’s mailbox.
`recipientAddress`	The address the hop was delivered to.
`provenance`	The provenance token, present when the send was signed.
`signed`	Whether the hop carried a verified signature.
`deliveryStatus`	How delivery landed — `delivered` for a completed hop.
`error`	The failure reason, or `null`.
`createdAt`	When the hop was recorded.

A receipt’s direction is sent or received — the mailbox list above uses inbound/outbound. Enumerate receipts with the list_a2a_messages tool ({ "action": "list", "limit": 50 }, filter by inboxId, page with cursor); each row’s id is the receipt id you pass to fetch one.

Next steps

Agent identity & provenance — the signatures these receipts record, and how a recipient verifies one.
The event ledger — the durable stream every hop also flows through.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Agent-to-agent messages

Read a2a messages from your mailbox

Inspect a hop receipt

Receipt fields

Next steps

​Read a2a messages from your mailbox

​Inspect a hop receipt

​Receipt fields

​Next steps

Read a2a messages from your mailbox

Inspect a hop receipt

Receipt fields

Next steps