# Mailbox API

Mailbox sends email and records outbound attempts within a project. Applications
can use the API to send transactional messages, inspect project delivery logs,
and manage the people, applications, or organizations that can use a project.
Personal and organization workspaces keep the authenticated caller distinct
from the principal that owns project access.

**Production API base:** `https://api.mailbox.service.m7.org/v1/`

Use the [Mailbox application](https://mailbox.service.m7.org/) to select a
workspace, manage projects and their members, compose mail, and inspect logs.

## Authenticate and select a project

Send an M7 access token as `Authorization: Bearer <access-token>`. The receiving
audience is exactly `https://api.mailbox.service.m7.org/`, including its trailing
slash. It is different from the versioned API base URL. A valid token and active
service access are required; each project action also requires the applicable
project capability. Organization requests additionally need verified
organization access and the `orgs` scope.

Read [authorization](https://m7.org/docs/api/api.mail.m7.org/authorization.md) before choosing a token profile, and
[workspaces](https://m7.org/docs/api/api.mail.m7.org/workspaces.md) before selecting an organization. Load
[project context](https://m7.org/docs/api/api.mail.m7.org/projects.md) and use its returned `capabilities` to enable
actions in your application.

## Requests and responses

The documented business endpoints use `POST` with `Content-Type:
application/json` and a JSON object. Paths in the guides are relative to the
production API base. UUID placeholders in examples must be replaced with
returned, dashed, non-nil UUIDs before sending a request.

```http
POST /v1/projects/list HTTP/1.1
Host: api.mailbox.service.m7.org
Authorization: Bearer <access-token>
Content-Type: application/json

{}
```

Successful business responses have this envelope; `data` depends on the route:

```json
{"status":1,"comment":"Mail project","data":{"items":[],"can_create":true}}
```

Business failures set an HTTP error status and return:

```json
{"status":0,"comment":"Capability denied: mail.send","data":{"code":403}}
```

An authentication or service-access rejection can occur before a business
handler runs. Its `code` and `reason` are top-level fields:

```json
{"status":0,"code":401,"comment":"Access denied","reason":"invalid_token"}
```

Check both the HTTP status and `status`. Comments are human-readable; avoid
using their exact text as an application protocol. Typical errors are `400`
for invalid input, `401` for missing or invalid credentials, `403` for denied
access, `404` for a missing record, `409` for a conflicting membership or
concurrent change, and `503` for unavailable authorization or service data.
Unexpected failures return `500` with a generic comment. A queued send means
the mail transport accepted the message; it does not confirm recipient delivery.

## Lists and navigation

Project lists and organization lists return complete arrays without pagination
inputs. Project-member lists use `limit` and `offset`, with nullable
`next_offset`. Send-log searches use `limit` and an opaque `next_cursor`, or an
offset/page number; stop when `next_cursor` is `null`. Each guide describes its
own defaults and limits.

* [Endpoints](https://m7.org/docs/api/api.mail.m7.org/endpoints.md) — supported routes and required actions.
* [Authorization](https://m7.org/docs/api/api.mail.m7.org/authorization.md) — access tokens, receiving audience, and proof boundaries.
* [Sending mail](https://m7.org/docs/api/api.mail.m7.org/sending.md) — fields, normalization, queue response, and retries.
* [Send logs](https://m7.org/docs/api/api.mail.m7.org/send-log.md) — project scope, filtering, pagination, and message details.
* [Projects](https://m7.org/docs/api/api.mail.m7.org/projects.md) — create, list, context, and delete.
* [Project members](https://m7.org/docs/api/api.mail.m7.org/project-members.md) — roles, membership changes, and capability selections.
* [Workspaces](https://m7.org/docs/api/api.mail.m7.org/workspaces.md) — caller identity, organization discovery, and selection.