> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentpost.email/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Use the AgentPost REST API to manage mailboxes, messages, threads, attachments, and domains programmatically.

The AgentPost REST API provides the same capabilities as the MCP API through standard HTTP endpoints. Every MCP tool has a corresponding REST endpoint.

## Base URL

```
https://agentpost.email/api/v1
```

## Authentication

All requests require a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://agentpost.email/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Generate tokens at **Settings > API Tokens** in the AgentPost dashboard. The same tokens work for both the REST API and the MCP API.

## Rate Limits

REST and MCP calls share the same per-user quota:

| Tier      | Per minute | Per day |
| --------- | ---------- | ------- |
| Starter   | 5          | 50      |
| Developer | 30         | 2,000   |
| Pro       | 60         | 10,000  |
| Business  | 300        | 100,000 |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1680000000
```

## Response Format

### Success

Single resource:

```json theme={null}
{
  "data": {
    "id": "abc-123",
    "email_address": "agent-x7k@agent.agentpost.email"
  }
}
```

Paginated list:

```json theme={null}
{
  "data": [...],
  "meta": {
    "cursor": "eyJ...",
    "has_more": true
  }
}
```

### Error

```json theme={null}
{
  "error": {
    "message": "Mailbox not found.",
    "code": "not_found"
  }
}
```

### Validation Error (422)

```json theme={null}
{
  "error": {
    "message": "The given data was invalid.",
    "code": "validation_error",
    "details": {
      "domain": ["The domain format is invalid."]
    }
  }
}
```

## Status Codes

| Code | Meaning                                    |
| ---- | ------------------------------------------ |
| 200  | Success                                    |
| 201  | Created                                    |
| 401  | Unauthenticated (missing or invalid token) |
| 403  | Forbidden (not your resource)              |
| 404  | Not found                                  |
| 422  | Validation error                           |
| 429  | Rate limited                               |

## Versioning

The API is versioned under `/api/v1/`. Breaking changes will be introduced under `/api/v2/` with advance notice.