Email infrastructure for AI agents. Create accounts, send/receive emails, manage webhooks, and check karma balance via the AgentMail API.
SKILL.md
AgentMail — Email for AI Agents
AgentMail gives AI agents real email addresses (@theagentmail.net) with a REST API. Agents can send and receive email, sign up for services (GitHub, AWS, Slack, etc.), and get verification codes. A karma system prevents spam and keeps the shared domain's reputation high.
Base URL: https://api.theagentmail.net
When to Use
An AI agent needs a real inbox/outbox for signups, verification flows, or transactional communication.
You need to provision AgentMail accounts, send messages, read inbox contents, or register inbound webhooks.
You need to monitor karma usage or wire email events into agent automation.
Quick start
All requests require Authorization: Bearer am_... header (API key from dashboard).
curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{
"to": ["[email protected]"],
"subject": "Hello from my agent",
"text": "Plain text body",
"html": "<p>Optional HTML body</p>"
}'
Optional fields: cc, bcc (string arrays), inReplyTo, references (strings for threading), attachments (array of {filename, contentType, content} where content is base64).
Read inbox
# List messages
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..."
# Get full message (with body and attachments)
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
-H "Authorization: Bearer am_..."
Karma is only awarded for inbound emails from trusted providers (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, etc.). Emails from unknown/throwaway domains don't earn karma.
You only earn karma once per sender until the agent replies. If sender X emails you 5 times without a reply, only the first earns karma. Reply to X, and the next email from X earns karma again.
Deleting an account refunds the 10 karma it cost to create.
When karma reaches 0, sends and account creation return HTTP 402. Always check balance before operations that cost karma.
TypeScript SDK
import { createClient } from "@agentmail/sdk";
const mail = createClient({ apiKey: "am_..." });
// Create account
const account = await mail.accounts.create({
address: "[email protected]",
});
// Send email
await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Hello",
text: "Sent by an AI agent.",
});
// Read inbox
const messages = await mail.messages.list(account.id);
const detail = await mail.messages.get(account.id, messages[0].id);
// Attachments
const att = await mail.attachments.getUrl(accountId, messageId, attachmentId);
// att.url is a signed download URL
// Webhooks
await mail.webhooks.create(account.id, {
url: "https://my-agent.example.com/inbox",
});
// Karma
const karma = await mail.karma.getBalance();
console.log(karma.balance);
Error handling
import { AgentMailError } from "@agentmail/sdk";
try {
await mail.messages.send(accountId, { to: ["[email protected]"], subject: "Hi", text: "Hey" });
} catch (e) {
if (e instanceof AgentMailError) {
console.log(e.status); // 402, 404, 401, etc.
console.log(e.code); // "INSUFFICIENT_KARMA", "NOT_FOUND", etc.
console.log(e.message);
}
}
Common patterns
Sign up for a service and read verification email
const account = await mail.accounts.create({
address: "[email protected]",
});
// Use the address to sign up (browser automation, API, etc.)
// Poll for verification email
for (let i = 0; i < 30; i++) {
const messages = await mail.messages.list(account.id);
const verification = messages.find(m =>
m.subject.toLowerCase().includes("verify") ||
m.subject.toLowerCase().includes("confirm")
);
if (verification) {
const detail = await mail.messages.get(account.id, verification.id);
// Parse verification link/code from detail.bodyText or detail.bodyHtml
break;
}
await new Promise(r => setTimeout(r, 2000));
}
Send email and wait for reply
const sent = await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Question about order #12345",
text: "Can you check the status?",
});
for (let i = 0; i < 60; i++) {
const messages = await mail.messages.list(account.id);
const reply = messages.find(m =>
m.direction === "inbound" && m.timestamp > sent.timestamp
);
if (reply) {
const detail = await mail.messages.get(account.id, reply.id);
// Process reply
break;
}
await new Promise(r => setTimeout(r, 5000));
}
