Skip to content

LeoYeAI/agent-master-skills / skills/agentmail

agentmail

Unverified

API-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.

FileKindSize
SKILL.mdskill md5.9 KB
references/API.mdmarkdown4.3 KB
references/EXAMPLES.mdmarkdown13.8 KB
references/WEBHOOKS.mdmarkdown7.2 KB
scripts/check_inbox.pyscript7.6 KB
scripts/send_email.pyscript3.9 KB
scripts/setup_webhook.pyscript6.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"
)
```
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall