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

# API Reference

> Complete reference for the SimpleEmailAPI REST API

The Simple Email API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

## Base URL

```
https://api.simpleemailapi.dev/v1
```

## Authentication

The Simple Email API uses bearer tokens for authentication. Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer sea_live_xxxxx
```

<Warning>
  Keep your API keys secure. Do not share them in publicly accessible areas such as GitHub, client-side code, etc.
</Warning>

## Rate Limits

API requests are rate limited to ensure fair usage:

| Limit Type         | Limit          |
| ------------------ | -------------- |
| Requests           | 100 per minute |
| Concurrent Streams | 5              |

Standard rate limit headers are included in every response:

```http theme={null}
RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 1640995200
```

## Errors

The API uses [Connect RPC](https://connectrpc.com) error codes which map to standard HTTP status codes:

| Code                 | HTTP  | Description                                                |
| -------------------- | ----- | ---------------------------------------------------------- |
| `invalid_argument`   | `400` | Client specified an invalid argument.                      |
| `unauthenticated`    | `401` | Request not authenticated (missing/invalid token).         |
| `permission_denied`  | `403` | Client does not have sufficient permission.                |
| `not_found`          | `404` | A specified resource was not found.                        |
| `already_exists`     | `409` | The resource that a client tried to create already exists. |
| `resource_exhausted` | `429` | Rate limit exceeded or resource quota reached.             |
| `internal`           | `500` | Internal server error.                                     |

Error responses follow the Connect RPC JSON format:

```json theme={null}
{
  "code": "invalid_argument",
  "message": "The 'to' field must contain at least one recipient",
  "details": [
    {
      "type": "google.rpc.BadRequest",
      "value": "base64-encoded-proto-message"
    }
  ]
}
```