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 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 before choosing a token profile, and workspaces before selecting an organization. Load project context 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.

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:

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

Business failures set an HTTP error status and return:

{"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:

{"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 — supported routes and required actions.
  • Authorization — access tokens, receiving audience, and proof boundaries.
  • Sending mail — fields, normalization, queue response, and retries.
  • Send logs — project scope, filtering, pagination, and message details.
  • Projects — create, list, context, and delete.
  • Project members — roles, membership changes, and capability selections.
  • Workspaces — caller identity, organization discovery, and selection.