API reference

Every endpoint of the Maylee REST API, with parameters, request and response schemas, examples and code samples, generated from its OpenAPI specification.

Base URL        https://api.maylee.app/api/v1
Authentication  Authorization: Bearer mk_...
Content type    application/json

Each endpoint page below is generated from the OpenAPI 3.1 specification of the API, which the Maylee backend produces from its own code: parameters, request and response schemas, examples and code samples in cURL, JavaScript and Python. The same document is served without authentication on GET https://api.maylee.app/api/v1/openapi.json, so that you can generate a client before you even have a key.

Conventions

Scope: the scope the key must hold, stated on every endpoint. Without it: 403 INSUFFICIENT_SCOPE. Endpoints marked Send emails also need that permission on the key. See Authentication.
Cost: one quota unit per call, except bulk operations, which cost one unit per email. See Rate limits and quotas.
Identifiers are opaque strings. Dates are ISO 8601, in UTC.
A resource that belongs to another workspace returns 404, never 403: a 403 would confirm that it exists.
Errors that can happen on every endpoint are not repeated on each page: 401 (missing, invalid, revoked or expired key), 403 WORKSPACE_SUSPENDED, 429 (rate limit or monthly quota), 413 PAYLOAD_TOO_LARGE and 500 INTERNAL_ERROR. See Errors.

Endpoints

Emails

List, search and read the emails of every connected mailbox, mark them read or starred, label them, and move them to the trash. Bodies are fetched on demand, and nothing is ever deleted permanently.

Drafts

Create drafts that a person reviews and sends from the Maylee app, or send an email immediately.

Mailboxes

Connected mailboxes, read-only: connecting one goes through OAuth or credentials in the Maylee app, never through a key.

get/mailboxesList connected mailboxes

Signatures

Signatures of the workspace, read-only: they are written in the Maylee app. Use an id as `signature` on a send or a draft; without it, Maylee signs like the app would.

get/signaturesList signatures

Labels

Manual labels are created here and applied by people, or by you through the API. AI labels show up in the same list with `isAiLabel: true`; they are renamed or deleted through their AI label rule.

AI label rules

An AI label plus a condition written in plain language. Maylee reads each incoming email and applies the label when the condition holds. A rule can also prepare replies (auto-draft) and send them (auto-reply).

Views

Saved filter trees, shown in the Maylee sidebar. Apply one with `?viewId=` on `GET /emails`.

Inbox filters

Hide matching emails from the main inbox without moving them. Filters are evaluated when listing, so they apply to past emails too.

Auto-forward rules

Forward every incoming email that matches a condition to another address. Managing rules requires the Send emails permission on the key.

Not available through the API yet

So that you do not look for them:

Downloading or sending attachments. Only their metadata is exposed.
Connecting a mailbox, or restricting a view to specific mailboxes. Both are done in the app.
Editing or deleting drafts. Drafts can be created, listed and read; a person changes or discards them in the app. POST /drafts/send sends immediately and does not create a draft.
Moving an email between folders, other than to the trash.
Permanent deletion. By design: a mistake can always be undone from the trash.
Managing API keys with a key. Keys are created and revoked in the app, by owners and admins, so that a leaked key cannot mint new ones.
Webhooks. They are coming soon.