Module 08 — AgentMail Setup
⏱️ 10 minutes
✨ Why AgentMail?
Think of AgentMail as your AI's own personal mailbox — it's free, it's made for agents, and it keeps your regular email tidy.
Other options:
- Gmail: Create a fresh account just for your agent
- Your domain: Set up
agent@yourdomain.com
Keep it separate from your personal email.
🔑 CRITICAL: The JSON Format That Makes Emails Work
Most email sending problems come from wrong JSON format. Always use both text and html at the top level (not nested in a body object):
{
"to": "recipient@example.com",
"subject": "My Subject",
"text": "Plain text fallback",
"html": "This is HTML with a link
"
}
Why both? Text is fallback for clients that don't render HTML. Always provide both — it improves deliverability.
Pro tip: Create a skill with this JSON format so your agent remembers it.
⚠️ Warning: Don't Mix Email Lives
Your agent will read, send, and forward email automatically. Use AgentMail (or a fresh Gmail) for agent stuff. Your real email for human stuff.
Let's get your agent its own mailbox
1
Go get an AgentMail inbox
- Visit https://agentmail.to
- Sign up for a free inbox (e.g.,
yourname-agent)
- Check your email for a verification link
- Log into your new inbox
2
Grab your API token
- In your AgentMail inbox, look for "API" or "Tokens"
- Click "Generate new token" — name it
My Heyron Agent
- Copy the token now — you won't see it again
⚠️ This token is like a password. Save it somewhere safe!
3
Connect your agent
Tell your agent:
"Connect to AgentMail. My inbox is [your-inbox]@agentmail.to and here's my token: [paste-token]"
It will test the connection and confirm it's working.
4
Test it
"Send a test email to my regular email"
Check both inboxes to confirm it went through.
⚠️ Common Issues
- Blank emails / HTML not rendering: Wrong JSON format. Use both
text AND html at top level (not nested in body). Without html, you just get plain text.
- Links get blocked: First emails with links often get flagged. Send your first message plain, add links in follow-ups.
- Attachments: Max 20-25MB. Don't send images inline in first emails — send as links instead.
Full documentation: https://docs.agentmail.to/messages
✨ Look what you've built!
Your agent now has:
- Chat (Discord — Module 03)
- Memory (GitHub — Module 04)
- Vision (Images — Module 05)
- Scheduling (Cron — Module 07)
- Email (AgentMail — right now)
A full digital assistant.