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

# Introduction

> Overview of the Mailofly REST API, authentication, and core resources.

# API Overview

**Base URL:** `https://api.mailofly.com` (paths are `/v1/...`, e.g. `https://api.mailofly.com/emails`)

<Info>
  **Legacy:** `https://www.mailofly.com/api/v1/...` on the web app remains available during migration; new integrations should use `api.mailofly.com/v1/...`.
</Info>

***

## Quick start

```bash theme={null}
# 1. Discover resources (no auth)
curl -sS "https://api.mailofly.com" \
  -H "Accept: application/json"

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

# 3. Make an authenticated call
curl -sS "https://api.mailofly.com/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 theme={null}
{
  "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 theme={null}
{
  "data": [ … ],
  "meta": { "page": 1, "page_size": 50, "total": 142 }
}
```

Single resources:

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

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

### Errors

```json theme={null}
{
  "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](accounts.md) | `/v1/accounts` | SMTP & Google sending identities |
| [Segments](segments.md) | `/v1/segments` | Audiences |
| [Segment contacts](segment-contacts.md) | `/v1/segments/{id}/contacts` | Segment membership |
| [Contacts](contacts.md) | `/v1/contacts` | People records |
| [Templates](templates.md) | `/v1/templates` | Email content |
| [Campaigns](campaigns.md) | `/v1/campaigns` | Campaigns, runs & send |
| [Emails](emails.md) | `/v1/emails`, `/v1/emails/batch` | Transactional single + batch send |
| [Mail logs](mail-logs.md) | `/v1/mail-logs` | Delivery history |

***

## Pagination

List endpoints accept:

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

***

## Send email (transactional)

Use **`GET /emails`** to list sent transactional emails with cursor pagination (`limit`, `after`, `before`) or **`GET /emails/:id`** to retrieve one (includes `html`). Send with **`POST /emails`** or batch with **`POST /emails/batch`**, plus optional **`account_key`** (`acc_…`):

```json theme={null}
POST /emails
{
  "from": "Acme <onboarding@example.com>",
  "to": ["user@example.com"],
  "subject": "Hello",
  "html": "<p>Hi</p>",
  "account_key": "acc_…"
}
```

Optional: `cc`, `bcc`, `reply_to`, `headers`, `tags`, `attachments`, `template` (`{ id, variables }`). Returns `{ "id": "mail-log-uuid" }`.

See **[Emails API](emails.md)**. The legacy `/v1/compose` endpoint has been removed.

***

## 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)
* [API: Emails](https://docs.mailofly.com/api/emails)
* [External Integrations](https://docs.mailofly.com/integrations)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.