# API reference

> Every Mailmanny API v1 endpoint, its permission and where it's documented.

Source: https://www.mailmanny.com/docs/api-reference
All docs for AI agents: https://www.mailmanny.com/llms.txt

One base URL, JSON in and out, snake_case fields, Bearer authentication. Every endpoint below links to its guide.

## Basics

- Base URL: `https://www.mailmanny.com/api/v1`
- Authentication: `Authorization: Bearer mm_live_…` ([details](https://www.mailmanny.com/docs/authentication.md))
- Bodies are JSON with `Content-Type: application/json`. Timestamps are ISO 8601 in UTC; ids are UUIDs.
- Lists return `{ object: "list", data, has_more, next_cursor }`. Pass `?cursor=` and `?limit=` (1–100) to page.
- Errors return `{ statusCode, name, message }` ([all errors](https://www.mailmanny.com/docs/errors.md)).

## Emails

- `POST /api/v1/emails`: Send an email (`emails:send`)
- `POST /api/v1/emails/batch`: Send up to 100 emails (`emails:send`)
- `GET /api/v1/emails/{id}`: Status and timestamps (`emails:send`)

## Audiences & contacts

- `GET /api/v1/audiences`: List audiences (`contacts:read`)
- `GET /api/v1/audiences/{id}`: Get an audience (`contacts:read`)
- `POST /api/v1/audiences/{id}/contacts`: Add or update a contact (`contacts:write`)
- `GET /api/v1/audiences/{id}/contacts`: List contacts (`contacts:read`)
- `GET /api/v1/audiences/{id}/contacts/{email_or_id}`: Get a contact (`contacts:read`)
- `PATCH /api/v1/audiences/{id}/contacts/{email_or_id}`: Update or unsubscribe (`contacts:write`)
- `DELETE /api/v1/audiences/{id}/contacts/{email_or_id}`: Archive or erase (`contacts:write`)
- `POST /api/v1/audiences/{id}/contacts/{email_or_id}/tags`: Add and remove tags (`contacts:write`)

## Events

- `POST /api/v1/events`: Track an event, start automations (`events:write`)

## Templates

- `GET /api/v1/templates`: List templates (`templates:read`)
- `GET /api/v1/templates/{id_or_external_id}`: Get a template with its HTML (`templates:read`)
- `PUT /api/v1/templates/{external_id}`: Create or update an HTML template (`templates:write`)
- `DELETE /api/v1/templates/{id_or_external_id}`: Delete a template (`templates:write`)