LeoYeAI/agent-master-skills / skills/agentmail
agentmail
UnverifiedAPI-first email platform designed for AI agents. Create and manage dedicated email inboxes, send and receive emails programmatically, and handle email-based workflows with webhooks and real-time events. Use when you need to set up agent email identity, send emails from agents, handle incoming email workflows, or replace traditional email providers like Gmail with agent-friendly infrastructure.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| references/API.md | markdown | 4.3 KB |
| references/EXAMPLES.md | markdown | 13.8 KB |
| references/WEBHOOKS.md | markdown | 7.2 KB |
| scripts/check_inbox.py | script | 7.6 KB |
| scripts/send_email.py | script | 3.9 KB |
| scripts/setup_webhook.py | script | 6.0 KB |
references/API.md
View on GitHub# AgentMail API Reference
Base URL: `https://api.agentmail.to/v0`
## Authentication
All requests require Bearer token authentication:
```
Authorization: Bearer YOUR_API_KEY
```
## Inboxes
### Create Inbox
```http
POST /v0/inboxes
```
**Request:**
```json
{
"username": "my-agent", // Optional: custom username
"domain": "agentmail.to", // Optional: defaults to agentmail.to
"display_name": "My Agent", // Optional: friendly name
"client_id": "unique-id" // Optional: for idempotency
}
```
**Response:**
```json
{
"pod_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"inbox_id": "my-agent@agentmail.to",
"display_name": "My Agent",
"created_at": "2024-01-10T08:15:00Z",
"updated_at": "2024-01-10T08:15:00Z",
"client_id": "unique-id"
}
```
### List Inboxes
```http
GET /v0/inboxes?limit=10&page_token=eyJwYWdlIjoxfQ==
```
**Response:**
```json
{
"count": 2,
"inboxes": [...],
"limit": 10,
"next_page_token": "eyJwYWdlIjoyMQ=="
}
```
### Get Inbox
```http
GET /v0/inboxes/{inbox_id}
```
## Messages
### Send Message
```http
POST /v0/inboxes/{inbox_id}/messages
```
**Request:**
```json
{
"to": ["recipient@example.com"], // Required: string or array
"cc": ["cc@example.com"], // Optional: string or array
"bcc": ["bcc@example.com"], // Optional: string or array
"reply_to": "reply@example.com", // Optional: string or array
"subject": "Email subject", // Optional: string
"text": "Plain text body", // Optional: string
"html": "<p>HTML body</p>", // Optional: string
"labels": ["sent", "important"], // Optional: array
"attachments": [{ // Optional: array of objects
"filename": "document.pdf",
"content": "base64-encoded-content",
"content_type": "application/pdf"
}],
"headers": { // Optional: custom headers
"X-Custom-Header": "value"
}
}
```
**Response:**
```json
{
"message_id": "msg_123abc",
"thread_id": "thd_789ghi"
}
```
### List Messages
```http
GET /v0/inboxes/{inbox_id}/messages?limit=10&page_token=token
```
### Get Message
```http
GET /v0/inboxes/{inbox_id}/messages/{message_id}
```
## Threads
### List Threads
```http
GET /v0/inboxes/{inbox_id}/threads?limit=10
```
### Get Thread
```http
GET /v0/inboxes/{inbox_id}/threads/{thread_id}
```
**Response:**
```json
{
"thread_id": "thd_789ghi",
"inbox_id": "support@example.com",
"subject": "Question about my account",
"participants": ["jane@example.com", "support@example.com"],
"labels": ["customer-support"],
"message_count": 3,
"last_message_at": "2023-10-27T14:30:00Z",
"created_at": "2023-10-27T10:00:00Z",
"updated_at": "2023-10-27T14:30:00Z"
}
```
## Webhooks
### Create Webhook
```http
POST /v0/webhooks
```
**Request:**
```json
{
"url": "https://your-domain.com/webhook",
"client_id": "webhook-identifier",
"enabled": true,
"event_types": ["message.received"], // Optional: defaults to all events
"inbox_ids": ["inbox1@domain.com"] // Optional: filter by specific inboxes
}
```
### List Webhooks
```http
GET /v0/webhooks
```
### Update Webhook
```http
PUT /v0/webhooks/{webhook_id}
```
### Delete Webhook
```http
DELETE /v0/webhooks/{webhook_id}
```
## Error Responses
All errors follow this format:
```json
{
"error": {
"type": "validation_error",
"message": "Invalid email address",
"details": {
"field": "to",
"code": "INVALID_EMAIL"
}
}
}
```
Common error codes:
- `400` - Bad Request (validation errors)
- `401` - Unauthorized (invalid API key)
- `404` - Not Found (resource doesn't exist)
- `429` - Too Many Requests (rate limited)
- `500` - Internal Server Error
## Rate Limits
AgentMail is designed for high-volume use with generous limits:
- API requests: 1000/minute per API key
- Email sending: 10,000/day (upgradeable)
- Webhook deliveries: Real-time, no limits
## Python SDK
The Python SDK provides a convenient wrapper around the REST API:
```python
from agentmail import AgentMail
import os
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
# All operations return structured objects
inbox = client.inboxes.create(username="my-agent")
message = client.inboxes.messages.send(
inbox_id=inbox.inbox_id,
to="user@example.com",
subject="Hello",
text="Message body"
)
```Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |