> For the complete documentation index, see [llms.txt](https://docs.mailofly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailofly.com/api-reference/readme.md).

# API overview

Mailofly exposes a REST **v1** API for managing sending accounts, audiences, templates, campaigns, and one-off sends — all scoped to your organization.

**Base URL:** `https://www.mailofly.com`

{% hint style="info" %}
The in-app **API panel** (command palette → "Open API documentation") shows contextual examples for the page you're on.
{% endhint %}

***

## Quick start

```bash
# 1. Discover resources (no auth)
curl -sS "https://www.mailofly.com/api/v1" \
  -H "Accept: application/json"

# 2. Create an API key in the app → copy mf_live_… secret

# 3. Make an authenticated call
curl -sS "https://www.mailofly.com/api/v1/accounts" \
  -H "Authorization: Bearer mf_live_your_key" \
  -H "Accept: application/json"
```

***

## Authentication

| Header          | Value                               |
| --------------- | ----------------------------------- |
| `Authorization` | `Bearer mf_live_…`                  |
| `Accept`        | `application/json`                  |
| `Content-Type`  | `application/json` (for POST/PATCH) |

Missing or invalid keys return **401**:

```json
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

Create keys at [**API keys**](https://www.mailofly.com/user/api-keys).

***

## Response format

### Success

List endpoints wrap results:

```json
{
  "data": [ … ],
  "meta": { "page": 1, "page_size": 50, "total": 142 }
}
```

Single resources:

```json
{
  "data": { "id": "uuid", "name": "…" }
}
```

Creates return **201** with `{ "data": … }`.

### Errors

```json
{
  "error": "ValidationError",
  "message": "segment_id is required"
}
```

| Code  | Meaning                            |
| ----- | ---------------------------------- |
| `400` | Invalid request body or parameters |
| `401` | Missing or bad API key             |
| `403` | Insufficient role or plan limit    |
| `404` | Resource not found in your org     |
| `429` | Rate limit exceeded                |
| `500` | Server error — retry with backoff  |

***

## Resources

| Resource                                                        | Base path                        | Description                      |
| --------------------------------------------------------------- | -------------------------------- | -------------------------------- |
| [Accounts](/api-reference/rest-api/accounts.md)                 | `/api/v1/accounts`               | SMTP & Google sending identities |
| [Segments](/api-reference/rest-api/segments.md)                 | `/api/v1/segments`               | Audiences                        |
| [Segment contacts](/api-reference/rest-api/segment-contacts.md) | `/api/v1/segments/{id}/contacts` | Segment membership               |
| [Contacts](/api-reference/rest-api/contacts.md)                 | `/api/v1/contacts`               | People records                   |
| [Templates](/api-reference/rest-api/templates.md)               | `/api/v1/templates`              | Email content                    |
| [Campaigns](/api-reference/rest-api/campaigns.md)               | `/api/v1/campaigns`              | Campaigns, runs & send           |
| [Compose](/api-reference/rest-api/compose.md)                   | `/api/v1/compose`                | One-off send via `account_key`   |
| [Mail logs](/api-reference/rest-api/mail-logs.md)               | `/api/v1/mail-logs`              | Delivery history                 |

***

## Pagination

List endpoints accept:

| Param       | Default | Max |
| ----------- | ------- | --- |
| `page`      | 1       | —   |
| `page_size` | 50      | 100 |

***

## Compose vs CRUD

Most resources use standard CRUD. **Compose** is special — it sends mail immediately using an **`account_key`** (`acc_…`) instead of an account UUID:

```json
POST /api/v1/compose
{
  "account_key": "acc_…",
  "subject": "Hello",
  "body": "<p>Hi</p>",
  "recipients": { "emails": ["user@example.com"] }
}
```

Find `account_key` on the [**Accounts**](https://www.mailofly.com/user/accounts) page.

***

## Rate limits

| Plan       | API requests/month |
| ---------- | ------------------ |
| Free       | 3,000              |
| Basic      | 15,000             |
| Scale      | 75,000             |
| Enterprise | Unlimited          |

Each authenticated request is logged. Monitor at [**API usage**](https://www.mailofly.com/user/api-usage).

***

## Plan enforcement

API operations respect organization plan limits. Exceeding a limit returns **403** with a descriptive message:

* `max_accounts`, `max_contacts`, `max_templates`
* `max_campaigns_per_month`, `monthly_email_quota`
* `allow_automation`, `allow_google_sheet_sync`

Upgrade at [**Billing**](https://www.mailofly.com/user/billing).

***

## Code examples

All endpoint pages include copy-paste **cURL** examples. Replace:

| Placeholder             | With                                          |
| ----------------------- | --------------------------------------------- |
| `mf_live_your_key_here` | Your API key secret                           |
| `uuid`                  | Actual resource ID from list/create responses |
| `acc_…`                 | Account key from Accounts page                |

***

## Related

* [Getting started → API keys](https://docs.mailofly.com/getting-started/api-keys)
* [Guides → Compose](https://docs.mailofly.com/guides/compose)
* [External Integrations](https://docs.mailofly.com/integrations)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mailofly.com/api-reference/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.