~/mailgi $ _

Your agent needs an email.

A real one. With an inbox, outbox, and an address that doesn't look like a UUID.

        →
        
          Register in one POST. No OAuth. No dashboard. No feelings.
        
        →
        
          Every agent gets a handle like buzzing-falcon@mailgi.xyz.
           (yes, it's random. yes, it's intentional.)
        
        →
        
          Send, receive, and read mail via a clean REST API.
          Backed by a real SMTP/IMAP server under the hood.
        
        →
        
          Everything is free. No credit card, no crypto.
           (rate limited to prevent spam — 100 external emails/day per agent)
        
        →
        
          No SDKs required. Just HTTP.
           (there is an SDK though, if you're into that sort of thing)

SKILL.md — for your agent, not you ↓ Download SKILL.md

Full API reference written so an AI agent can read it and immediately start sending mail. No OpenAPI parsing. No SDK. Just words.

# In your CLAUDE.md or at the start of a session:

Fetch https://mailgi.xyz/SKILL.md and follow the instructions to give the agent an email address.

# Or let Claude Code fetch it directly:
> Read https://mailgi.xyz/SKILL.md then register me an agent

# Add to your agent's tool list or system context:

claw fetch https://mailgi.xyz/SKILL.md --inject system

# Or reference it as a skill source in your claw config:
skills:
- url: https://mailgi.xyz/SKILL.md
name: mailgi-email

# Paste this into any system prompt:

You have access to a real email API. Fetch
https://mailgi.xyz/SKILL.md to learn how to use it.
Register an address, then use it to send and receive mail.

# Or inline the file directly — it's ~3KB, fits in any context window.

# Register — get an email address and API key
curl -X POST https://api.mailgi.xyz/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"label":"my-agent"}'
# => { "emailAddress": "buzzing-falcon@mailgi.xyz", "apiKey": "amb_..." }

# Send an email
curl -X POST https://api.mailgi.xyz/v1/mail/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["alice@example.com"],"subject":"Hi","textBody":"Hello"}'

# Read inbox
curl https://api.mailgi.xyz/v1/mail \
  -H "Authorization: Bearer $KEY"

# Read a specific message
curl https://api.mailgi.xyz/v1/mail/<id> \
  -H "Authorization: Bearer $KEY"

# Install
npm install -g @mailgi/mailgi

# Register — saves credentials to ~/.mailgi/config.json
mailgi register --label my-agent
# => registered buzzing-falcon@mailgi.xyz

# Add an existing agent by API key
mailgi login --agent buzzing-falcon@mailgi.xyz --apikey amb_...

# Send an email
mailgi send --agent buzzing-falcon \
  --to alice@example.com \
  --subject "Hi" \
  --body "Hello from my agent"

# Read inbox
mailgi inbox --agent buzzing-falcon

# Read a message
mailgi read --agent buzzing-falcon <message-id>

// Install
npm install @mailgi/mailgi

// TypeScript / Node.js
import { AgentMailboxClient } from '@mailgi/mailgi';

const client = AgentMailboxClient.withApiKey(
  'https://api.mailgi.xyz',
  process.env.MAILGI_API_KEY,
);

// Send an email
await client.mail.send({
  to: ['alice@example.com'],
  subject: 'Hi',
  textBody: 'Hello from my agent.',
});

// Read inbox
const { messages } = await client.mail.list({ limit: 20, sort: 'desc' });
const email = await client.mail.get(messages[0].id);
console.log(email.subject, email.textBody);

Docs & Resources

Swagger UI Interactive API explorer — try every endpoint in the browser

api.mailgi.xyz/docs →

OpenAPI spec Machine-readable spec — import into Postman, Insomnia, or your agent

api.mailgi.xyz/openapi.json →

SKILL file Plain-language API description written for AI agents to self-onboard

SKILL.md ↓

Pricing

Inbound (any sender) free

Agent → agent (@mailgi.xyz) free

Outbound to humans (external domains) free

Rate limit 100 external / day / agent