How to Give Your AI Agent an Email Address
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:
- 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.
- SendGrid / Resend / Postmark — Great for transactional email (password resets, receipts), but they're send-only. Your agent can't receive replies.
- Self-hosted Postfix — Full control, full ops nightmare. DNS records, TLS certificates, spam filtering, IP reputation — all on you.
- 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.
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 — [email protected].
curl -X POST https://api.robotomail.com/v1/signup \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "a-secure-password",
"slug": "my-agent"
}'You get back everything you need:
{
"user": {
"slug": "my-agent",
"platform_email": "[email protected]"
},
"api_key": {
"key": "rm_a1b2c3d4..."
},
"mailbox": {
"id": "mbx_abc123",
"address": "my-agent",
"fullAddress": "[email protected]",
"status": "ACTIVE"
},
"daily_send_limit": 50,
"monthly_send_limit": 1000,
"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": ["[email protected]"],
"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": "[email protected]",
"toAddresses": ["[email protected]"],
"subject": "Your report is ready",
"direction": "OUTBOUND",
"status": "SENT",
"messageId": "<[email protected]>",
"createdAt": "2026-03-20T14:30:00Z"
}
}That's it. A real email, delivered to a real inbox. Free tier gives you 50 sends per day and 1,000 per month per mailbox. See the full messages API reference 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. 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": "[email protected]",
"toAddresses": ["[email protected]"],
"subject": "Re: Your report is ready",
"body_text": "Looks great, but can you regenerate the chart on page 3?",
"in_reply_to": "<[email protected]>",
"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": ["[email protected]"],
"subject": "Re: Your report is ready",
"bodyText": "Done — the chart on page 3 has been regenerated with the latest data.",
"inReplyTo": "<[email protected]>"
}'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": "[email protected]",
"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": ["[email protected]"],
"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: "[email protected]",
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: ["[email protected]"],
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:
- Custom domains — Send from
[email protected]instead of the platform address. Add your domain via the API and configure the DNS records Robotomail generates for you. - Higher send limits — Free tier gives you 50 sends/day and 1,000/month. Upgrade to paid for 1,000 sends/day, 5,000/month, and multiple mailboxes.
- 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 - Attachments — Upload files to send with your emails. 1 GB storage included on the free tier.
Check the quickstart guide for the full walkthrough, or dive into the messages and webhooks API references.
Give your agent an email address
The free tier includes a mailbox, 50 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.