Give your AI agent an email address

This is a practical, end-to-end guide. By the end you'll have a working inbox, an agent that can receive and reply to email, and a live stream of delivery events. We'll show each step in TypeScript and Python, plus the equivalent MCP tool call so your agent can do it directly.

You'll need a Dairo API key. Create one in the dashboard under API Keys, then export it as DAIRO_API_KEY. Install the SDK for your language: npm install dairo or pip install dairo.

Step 1 — Create an inbox

An inbox is the agent's address. Create one and you immediately get a real, receivable email address on the default Dairo domain. (Want to send from your own domain? Verify it first — we cover that at the end.)

TypeScript
import { Dairo } from "dairo";

const dairo = new Dairo({ apiKey: process.env.DAIRO_API_KEY });

const inbox = await dairo.inboxes.create({ name: "support-agent" });
console.log(inbox.address); // → [email protected]

Python
import os
from dairo import Dairo

dairo = Dairo(api_key=os.environ["DAIRO_API_KEY"])

inbox = dairo.inboxes.create(name="support-agent")
print(inbox.address)  # → [email protected]

Step 2 — Hand the address to your agent

Now give the agent its address. How you do this depends on your framework, but the pattern is the same: put inbox.address in the system prompt or tool context so the agent knows where it can be reached, and store inbox.id so you can poll or subscribe to it later.

Tell whoever needs to contact the agent to email that address. From here on, every message sent to it lands in Dairo and is available over the API.

Step 3 — Receive a message

List the messages in the inbox and fetch the full content of one. Responses are metadata-first, so you can cheaply list and then pull the body only for the message you care about.

TypeScript
const { data: messages } = await dairo.messages.list({ inboxId: inbox.id });
const latest = messages[0];

const message = await dairo.messages.get(latest.id);
console.log(message.from, message.subject);
console.log(message.text);

Each message carries stable join keys — id, threadId, inboxId — so your agent can persist a reference and resume the conversation later without re-fetching everything.

Step 4 — Reply

Replying is a send from the inbox's own address. Pass the original message so Dairo keeps the reply on the same conversation.

Python
dairo.messages.send(
    from_=inbox.address,
    to=message.from_,
    subject=f"Re: {message.subject}",
    text="Thanks for reaching out — here's what I found…",
    in_reply_to=message.id,
)

Step 5 — Do it all over MCP

If your agent talks to tools through the Model Context Protocol, it doesn't need any of this glue code. Point it at the Dairo MCP server and the same operations show up as tools. A receive-and-reply turn looks like this from the agent's side:

JSON
// Agent calls the read_mailbox tool over MCP
{ "tool": "read_mailbox", "arguments": { "inbox_id": "ibx_7f3a" } }

// …then replies with send_message
{ "tool": "send_message", "arguments": {
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Re: Order status",
    "text": "Your order shipped this morning."
} }

Step 6 — Stream delivery events

Knowing a send returned 200 isn't the same as knowing it was delivered. Dairo emits outbound events — accepted, delivered, bounced, complained — so your agent can react to what actually happened. Poll the events endpoint, or register a webhook to be notified.

TypeScript
const { data: events } = await dairo.outboundEvents.list({ inboxId: inbox.id });

for (const event of events) {
  console.log(event.type, event.email, event.timestamp);
  // → delivered  [email protected]  2026-06-11T09:14:02Z
}

Next: send from your own domain

The default inbox domain is perfect for getting started. When you're ready for agents to send from an address your users trust, verify a custom domain: add a domain, drop the DNS records Dairo gives you, and once it's verified your inboxes can send from it. The domains guide walks through the records.

That's the whole loop — create, receive, reply, observe. Everything here works identically across all nine SDKs and the CLI, so pick whichever fits your stack and ship.