> ## 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/v1/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/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://api.mailofly.com/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 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` | Resend-compatible 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 /v1/emails`** to list sent transactional emails (Resend cursor: `limit`, `after`, `before`) or **`GET /v1/emails/:id`** to retrieve one (includes `html`). Send with **`POST /v1/emails`** or batch with **`POST /v1/emails/batch`**. All match [Resend’s email APIs](https://resend.com/docs/api-reference/emails/send-email), plus optional **`account_key`** (`acc_…`):

```json theme={null}
POST /v1/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)


## Related topics

- [Introduction](/introduction.md)