# How to Give Your AI Agent an Email Address

Published: March 21, 2026

Step-by-step tutorial: create a mailbox, send an email, receive via webhook, and reply to a thread. Code examples in curl, Python, and TypeScript.

Your AI agent just finished a task. It needs to send a follow-up email to a customer. Or maybe it needs to _receive_ a reply and decide what to do next. Either way, it needs a real email address — one that can send and receive, not just fire off transactional blasts.

This tutorial walks you through giving your agent a fully functional email address in about five minutes, using [Robotomail](/). By the end you'll have working code that signs up, sends an email, and listens for replies.

## Your options (and why most of them hurt)

Before we jump into code, a quick survey of the landscape:

1.  **Gmail API** — OAuth consent screens, token refresh headaches, and Terms of Service that explicitly prohibit automated bulk sending. Fine for a personal project, risky for anything production.
2.  **SendGrid / Resend / Postmark** — Great for transactional email (password resets, receipts), but they're send-only. Your agent can't receive replies.
3.  **Self-hosted Postfix** — Full control, full ops nightmare. DNS records, TLS certificates, spam filtering, IP reputation — all on you.
4.  **A purpose-built agent email API** — One API call to get a mailbox. Send and receive. Webhooks for inbound. No OAuth, no ops. [That's Robotomail.](/blog/introducing-robotomail)

Let's go with option four.

## Step 1: Create an account

A single `POST /v1/signup` creates your user account, provisions your first mailbox, and returns an API key. The `slug` you choose becomes your permanent platform email address — `slug@robotomail.co`.

```
curl -X POST https://api.robotomail.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "a-secure-password",
    "slug": "my-agent"
  }'
```

You get back everything you need:

```
{
  "user": {
    "slug": "my-agent",
    "platform_email": "my-agent@robotomail.co"
  },
  "api_key": {
    "key": "rm_a1b2c3d4..."
  },
  "mailbox": {
    "id": "mbx_abc123",
    "address": "my-agent",
    "fullAddress": "my-agent@robotomail.co",
    "status": "ACTIVE"
  },
  "daily_send_limit": 100,
  "monthly_send_limit": 5000,
  "email_verified": false
}
```

**Save the API key immediately** — it's only shown once. All subsequent requests use `Authorization: Bearer rm_a1b2c3d4...` for authentication.

A verification email is sent to your signup address. You'll need to click that link before your agent can send email. Receiving email and setting up webhooks works immediately.

## Step 2: Send your first email

Once verified, your agent can send email to any address. Pass the mailbox ID from the signup response and provide `to`, `subject`, and `bodyText`.

```
curl -X POST https://api.robotomail.com/v1/mailboxes/mbx_abc123/messages \
  -H "Authorization: Bearer rm_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your report is ready",
    "bodyText": "Hi — your weekly report is attached. Let me know if you have questions."
  }'
```

```
{
  "message": {
    "id": "msg_xyz789",
    "mailboxId": "mbx_abc123",
    "fromAddress": "my-agent@robotomail.co",
    "toAddresses": ["customer@example.com"],
    "subject": "Your report is ready",
    "direction": "OUTBOUND",
    "status": "SENT",
    "messageId": "<msg_xyz789@robotomail.co>",
    "createdAt": "2026-03-20T14:30:00Z"
  }
}
```

That's it. A real email, delivered to a real inbox. Free tier gives you 100 sends per day and 5,000 per month per mailbox. See the full [messages API reference](/docs/api/messages) for HTML bodies, CC/BCC, and attachments.

## Step 3: Receive email via webhook

Sending is half the story. To let your agent _react_ to incoming email, register a [webhook](/docs/api/webhooks). Robotomail will POST to your URL whenever a new message arrives.

```
curl -X POST https://api.robotomail.com/v1/webhooks \
  -H "Authorization: Bearer rm_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.received"]
  }'
```

The response includes a `secret` for verifying webhook signatures. Save it — it's only returned on creation.

```
{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook",
    "events": ["message.received"],
    "secret": "whsec_a1b2c3d4e5f6..."
  }
}
```

When someone replies to your agent's email, Robotomail sends a POST to your webhook URL with the full message:

```
{
  "event": "message.received",
  "timestamp": "2026-03-20T15:02:00Z",
  "data": {
    "message_id": "msg_inb456",
    "mailbox_id": "mbx_abc123",
    "fromAddress": "customer@example.com",
    "toAddresses": ["my-agent@robotomail.co"],
    "subject": "Re: Your report is ready",
    "body_text": "Looks great, but can you regenerate the chart on page 3?",
    "in_reply_to": "<msg_xyz789@robotomail.co>",
    "thread_id": "thr_001",
    "received_at": "2026-03-20T15:02:00Z"
  }
}
```

Verify every webhook by computing HMAC-SHA256 of the raw request body with your webhook secret and comparing it to the `X-Robotomail-Signature` header.

## Step 4: Reply to a thread

Your agent got a reply asking for a chart update. To continue the conversation in the same email thread, include the `inReplyTo` field with the original message's `messageId`. Robotomail handles threading automatically — it sets the `In-Reply-To` and `References` headers so the reply threads correctly in every email client.

```
curl -X POST https://api.robotomail.com/v1/mailboxes/mbx_abc123/messages \
  -H "Authorization: Bearer rm_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Re: Your report is ready",
    "bodyText": "Done — the chart on page 3 has been regenerated with the latest data.",
    "inReplyTo": "<msg_xyz789@robotomail.co>"
  }'
```

The reply shows up in the same thread on the recipient's end. Your agent can carry on multi-turn conversations just like a human would.

## Complete example: Python

Here's a minimal, copy-pasteable Python script that creates an account, sends an email, and registers a webhook. Uses `requests` only.

```
import requests

BASE = "https://api.robotomail.com"

# 1. Create an account
signup = requests.post(f"{BASE}/v1/signup", json={
    "email": "you@company.com",
    "password": "a-secure-password",
    "slug": "my-agent",
})
signup.raise_for_status()
data = signup.json()

api_key = data["api_key"]["key"]
mailbox_id = data["mailbox"]["id"]
print(f"Mailbox ready: {data['mailbox']['fullAddress']}")
print(f"API key (save this!): {api_key}")

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

# 2. Send an email
# (Requires email verification — click the link sent to your signup email first)
send = requests.post(f"{BASE}/v1/mailboxes/{mailbox_id}/messages", headers=headers, json={
    "to": ["customer@example.com"],
    "subject": "Your report is ready",
    "bodyText": "Hi — your weekly report is attached. Let me know if you have questions.",
})
send.raise_for_status()
msg = send.json()["message"]
print(f"Sent message {msg['id']} to {msg['toAddresses']}")

# 3. Register a webhook for inbound email
webhook = requests.post(f"{BASE}/v1/webhooks", headers=headers, json={
    "url": "https://your-server.com/webhook",
    "events": ["message.received"],
})
webhook.raise_for_status()
wh = webhook.json()["webhook"]
print(f"Webhook registered: {wh['id']}")
print(f"Webhook secret (save this!): {wh['secret']}")
```

## Complete example: TypeScript

Same flow in TypeScript with the built-in Fetch API.

```
const BASE = "https://api.robotomail.com";

async function main() {
  // 1. Create an account
  const signupRes = await fetch(`${BASE}/v1/signup`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "you@company.com",
      password: "a-secure-password",
      slug: "my-agent",
    }),
  });
  const { api_key, mailbox } = await signupRes.json();

  const apiKey = api_key.key;
  const mailboxId = mailbox.id;
  console.log(`Mailbox ready: ${mailbox.fullAddress}`);
  console.log(`API key (save this!): ${apiKey}`);

  const headers = {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  };

  // 2. Send an email
  // (Requires email verification — click the link sent to your signup email first)
  const sendRes = await fetch(`${BASE}/v1/mailboxes/${mailboxId}/messages`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      to: ["customer@example.com"],
      subject: "Your report is ready",
      bodyText:
        "Hi — your weekly report is attached. Let me know if you have questions.",
    }),
  });
  const { message } = await sendRes.json();
  console.log(`Sent message ${message.id} to ${message.toAddresses}`);

  // 3. Register a webhook for inbound email
  const webhookRes = await fetch(`${BASE}/v1/webhooks`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      url: "https://your-server.com/webhook",
      events: ["message.received"],
    }),
  });
  const { webhook } = await webhookRes.json();
  console.log(`Webhook registered: ${webhook.id}`);
  console.log(`Webhook secret (save this!): ${webhook.secret}`);
}

main().catch(console.error);
```

## What's next

You now have a working agent email address. Here's where to go from here:

1.  **Custom domains** — Send from `agent@yourdomain.com` instead of the platform address. Add your domain via the API and configure the DNS records Robotomail generates for you.
2.  **Higher send limits** — Free tier gives you 100 sends/day and 5,000/month. Upgrade to Developer for 500 sends/day per mailbox, 10 mailboxes, and custom domains.
3.  **SSE streaming** — Don't have a public URL for webhooks? Use Server-Sent Events to stream inbound messages in real time, or use the CLI: `robotomail listen --forward-to http://localhost:4000/hook`
4.  **Attachments** — Upload files to send with your emails. 1 GB storage included on the free tier.

Check the [quickstart guide](/docs/quickstart) for the full walkthrough, or dive into the [messages](/docs/api/messages) and [webhooks](/docs/api/webhooks) API references.

## Give your agent an email address

The free tier includes three mailboxes, 100 sends/day, and 1 GB of attachment storage. No credit card required. Sign up with one API call and your agent is sending email in under a minute.

[Start building — free](/sign-up)