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

# API Reference

> Complete reference for the MailBreeze REST API

## Base URL

All API requests are made to:

```
https://api.mailbreeze.com/api/v1
```

## Authentication

Include your API key in the `Authorization` header with a `Bearer` prefix:

```bash theme={null}
curl https://api.mailbreeze.com/api/v1/emails \
  -H "Authorization: Bearer sk_live_xxx"
```

<Note>
  Get your API key from the [MailBreeze Dashboard](https://console.mailbreeze.com/settings/api-keys).
</Note>

## Request Format

All requests should include:

| Header          | Value                   |
| --------------- | ----------------------- |
| `Content-Type`  | `application/json`      |
| `Authorization` | `Bearer <your-api-key>` |

Request bodies must be valid JSON:

```json theme={null}
{
  "from": "hello@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello!",
  "html": "<p>Welcome!</p>"
}
```

## Response Format

All responses are JSON wrapped in a standard envelope:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/emails"
  }
}
```

### Successful Response

Single resource:

```json theme={null}
{
  "success": true,
  "data": {
    "stats": {
      "total": 10000,
      "sent": 9850,
      "failed": 150
    }
  },
  "meta": { "timestamp": "...", "requestId": "...", "path": "..." }
}
```

Send email response:

```json theme={null}
{
  "success": true,
  "data": {
    "messageId": "abc123@mailbreeze.com",
    "skipped": false
  },
  "meta": { "timestamp": "...", "requestId": "...", "path": "..." }
}
```

### List Response

Paginated lists include a `pagination` object within `data`:

```json theme={null}
{
  "success": true,
  "data": {
    "emails": [
      { "id": "msg_abc123", "subject": "Hello" },
      { "id": "msg_def456", "subject": "Welcome" }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 123
    }
  },
  "meta": { "timestamp": "...", "requestId": "...", "path": "..." }
}
```

### Error Response

Errors also follow the envelope pattern:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address format",
    "details": {
      "field": "to",
      "value": "invalid-email"
    }
  },
  "meta": { "timestamp": "...", "requestId": "..." }
}
```

<Note>
  SDKs automatically extract the `data` field, so you access response data directly without the wrapper.
</Note>

## HTTP Methods

| Method   | Usage              |
| -------- | ------------------ |
| `GET`    | Retrieve resources |
| `POST`   | Create resources   |
| `PUT`    | Update resources   |
| `DELETE` | Remove resources   |

## Pagination

List endpoints support pagination:

| Parameter | Type    | Default | Description              |
| --------- | ------- | ------- | ------------------------ |
| `page`    | integer | 1       | Page number              |
| `limit`   | integer | 20      | Items per page (max 100) |

Example:

```bash theme={null}
curl "https://api.mailbreeze.com/api/v1/emails?page=2&limit=50" \
  -H "Authorization: Bearer sk_live_xxx"
```

## Timestamps

All timestamps are ISO 8601 format in UTC:

```
2024-01-15T10:30:00.000Z
```

## IDs

Resources use prefixed IDs for easy identification:

| Prefix | Resource      |
| ------ | ------------- |
| `msg_` | Email message |
| `lst_` | Contact list  |
| `cnt_` | Contact       |
| `att_` | Attachment    |
| `ver_` | Verification  |

## Test Mode

Use test API keys (`sk_test_*`) to simulate requests without sending real emails or using credits:

```typescript theme={null}
const mailbreeze = new MailBreeze({ apiKey: "sk_test_xxx" });

const result = await mailbreeze.emails.send({ ... });
console.log(result.sandbox); // true - email was simulated
```

## SDKs

Official SDKs are available for popular languages:

<CardGroup cols={3}>
  <Card title="JavaScript" icon="js" href="/sdks/javascript">
    npm install mailbreeze
  </Card>

  <Card title="Python" icon="python" href="/sdks/python">
    pip install mailbreeze
  </Card>

  <Card title="Go" icon="golang" href="/sdks/go">
    go get github.com/MailBreeze/mailbreeze-go
  </Card>

  <Card title="PHP" icon="php" href="/sdks/php">
    composer require mailbreeze/mailbreeze-php
  </Card>

  <Card title="Rust" icon="rust" href="/sdks/rust">
    cargo add mailbreeze
  </Card>
</CardGroup>