# Maylee Developers

> Developer documentation for Maylee, the AI email client: the REST API, the MCP server for AI assistants, and webhooks.

Maylee is an AI email client. The REST API lives at https://api.maylee.app/api/v1 (Bearer API keys `mk_...`), and the MCP server at https://mcp.maylee.app/mcp (OAuth 2.1 or an API key), being rolled out and not available yet. Every page below is Markdown; add `.md` to any page URL of this site to get its Markdown.

## Get started

- [Introduction](https://docs.maylee.app/index.md): Build on Maylee, the AI email client. Read, search, triage and send email across every mailbox of a workspace, from your own code or from an AI agent.
- [Authentication](https://docs.maylee.app/authentication.md): API keys, the read and write scopes, and the separate permission to send emails.
- [Common tasks](https://docs.maylee.app/common-tasks.md): Read a conversation, search, mark as read, send, prepare a draft for review, reply in a thread and let Maylee classify email, with copyable requests.
- [Rate limits and quotas](https://docs.maylee.app/rate-limits.md): Requests per minute and per month for each plan, the X-RateLimit headers, how usage is counted, and the hard limits of every request.
- [Errors](https://docs.maylee.app/errors.md): The error format, every error code the API returns, and what to do about each one.
- [Pagination](https://docs.maylee.app/pagination.md): Cursor pagination on email lists and search, sorting, and the reference lists that are returned in full.
- [Idempotency](https://docs.maylee.app/idempotency.md): Retry a send or a creation safely with the Idempotency-Key header, without doing it twice.
- [Filters](https://docs.maylee.app/filters.md): The JSON filter tree of GET /emails and saved views, its fields and operators, its bounds, and worked examples.

## API reference

- [API reference](https://docs.maylee.app/api-reference.md): Every endpoint of the Maylee REST API, with parameters, request and response schemas, examples and code samples, generated from its OpenAPI specification.
- Emails
  - [List emails](https://docs.maylee.app/api-reference/emails/list-emails.md): `GET /emails`. Use this to browse a mailbox or a saved view.
  - [Full-text search](https://docs.maylee.app/api-reference/emails/search-emails.md): `GET /emails/search`. Use this when looking for a keyword.
  - [Get an email](https://docs.maylee.app/api-reference/emails/get-email.md): `GET /emails/{emailId}`. Metadata of one email, without its body.
  - [Get an email body and its thread](https://docs.maylee.app/api-reference/emails/get-email-body.md): `GET /emails/{emailId}/body`. Returns the rendered body plus every message of the conversation, oldest first.
  - [Bulk mark-read, delete, apply or remove a label](https://docs.maylee.app/api-reference/emails/bulk-update-emails.md): `POST /emails/bulk`. Counts against the quota once per email processed, not once per request.
  - [Apply a label to an email](https://docs.maylee.app/api-reference/emails/apply-label-to-email.md): `POST /emails/{emailId}/labels/{labelId}`. Idempotent: applying a label the email already has returns the current labels without firing `label.applied` again.
  - [Update read or starred state](https://docs.maylee.app/api-reference/emails/update-email.md): `PATCH /emails/{emailId}`. Provide at least one of `isRead` or `isStarred`.
  - [Move an email to trash](https://docs.maylee.app/api-reference/emails/trash-email.md): `DELETE /emails/{emailId}`. Never a permanent delete: the message stays recoverable from trash.
  - [Remove a label from an email](https://docs.maylee.app/api-reference/emails/remove-label-from-email.md): `DELETE /emails/{emailId}/labels/{labelId}`. Idempotent: removing a label the email does not have is not an error.
- Drafts
  - [List drafts](https://docs.maylee.app/api-reference/drafts/list-drafts.md): `GET /drafts`. The most recent drafts of the workspace, up to `limit`.
  - [Get a draft](https://docs.maylee.app/api-reference/drafts/get-draft.md): `GET /drafts/{draftId}`
  - [Create a draft](https://docs.maylee.app/api-reference/drafts/create-draft.md): `POST /drafts`. Creates a draft in one of the workspace mailboxes without sending it.
  - [Send an email](https://docs.maylee.app/api-reference/drafts/send-email.md): `POST /drafts/send`. The only irreversible action in this API: it leaves the system and reaches a third party.
- Mailboxes
  - [List connected mailboxes](https://docs.maylee.app/api-reference/mailboxes/list-mailboxes.md): `GET /mailboxes`. Call this to resolve the `mailboxId` every send and most filters need.
- Signatures
  - [List signatures](https://docs.maylee.app/api-reference/signatures/list-signatures.md): `GET /signatures`. Call this to turn a signature name into the id that `signature` takes on a send or a draft.
- Labels
  - [List labels](https://docs.maylee.app/api-reference/labels/list-labels.md): `GET /labels`. Every label of the workspace, AI labels included.
  - [Get a label](https://docs.maylee.app/api-reference/labels/get-label.md): `GET /labels/{labelId}`
  - [Create a label](https://docs.maylee.app/api-reference/labels/create-label.md): `POST /labels`. Creates a manual label.
  - [Rename or recolor a label](https://docs.maylee.app/api-reference/labels/update-label.md): `PATCH /labels/{labelId}`. Manual labels only: an AI label is renamed through its rule on `/ai-label-rules`.
  - [Delete a label](https://docs.maylee.app/api-reference/labels/delete-label.md): `DELETE /labels/{labelId}`. Removes the label from every email that carries it.
- AI label rules
  - [List AI label rules](https://docs.maylee.app/api-reference/ai-label-rules/list-ai-label-rules.md): `GET /ai-label-rules`
  - [Get an AI label rule](https://docs.maylee.app/api-reference/ai-label-rules/get-ai-label-rule.md): `GET /ai-label-rules/{ruleId}`
  - [Create an AI label rule](https://docs.maylee.app/api-reference/ai-label-rules/create-ai-label-rule.md): `POST /ai-label-rules`. Creates the AI label and the natural-language condition that applies it, in one call.
  - [Classify existing emails with the AI label rules](https://docs.maylee.app/api-reference/ai-label-rules/classify-existing-emails.md): `POST /ai-label-rules/backfill`. Rules only apply to emails synchronized after their creation.
  - [Update an AI label rule](https://docs.maylee.app/api-reference/ai-label-rules/update-ai-label-rule.md): `PATCH /ai-label-rules/{ruleId}`. Renames the label, changes the condition, or configures auto-draft and auto-reply.
  - [Delete an AI label rule](https://docs.maylee.app/api-reference/ai-label-rules/delete-ai-label-rule.md): `DELETE /ai-label-rules/{ruleId}`. Deletes the rule and its label, and removes the label from every email that carried it.
- Views
  - [List saved views](https://docs.maylee.app/api-reference/views/list-views.md): `GET /views`. Apply one with `?viewId=` on `GET /emails`.
  - [Get a view](https://docs.maylee.app/api-reference/views/get-view.md): `GET /views/{viewId}`
  - [Create a view](https://docs.maylee.app/api-reference/views/create-view.md): `POST /views`. Saves a filter tree under a name.
  - [Update a view](https://docs.maylee.app/api-reference/views/update-view.md): `PATCH /views/{viewId}`. `filters` replaces the whole tree.
  - [Delete a view](https://docs.maylee.app/api-reference/views/delete-view.md): `DELETE /views/{viewId}`
- Inbox filters
  - [List inbox filters](https://docs.maylee.app/api-reference/inbox-filters/list-inbox-filters.md): `GET /filters`
  - [Get an inbox filter](https://docs.maylee.app/api-reference/inbox-filters/get-inbox-filter.md): `GET /filters/{filterId}`
  - [Create an inbox filter](https://docs.maylee.app/api-reference/inbox-filters/create-inbox-filter.md): `POST /filters`. Hides matching emails from the main inbox without moving them: they stay in INBOX, are listed by `GET /emails?filtered=only`, and remain visible in any view whose criteria match them.
  - [Update an inbox filter](https://docs.maylee.app/api-reference/inbox-filters/update-inbox-filter.md): `PATCH /filters/{filterId}`. Changes `type` and/or `value`.
  - [Delete an inbox filter](https://docs.maylee.app/api-reference/inbox-filters/delete-inbox-filter.md): `DELETE /filters/{filterId}`. The emails it hid reappear in the main inbox immediately.
- Auto-forward rules
  - [List auto-forward rules](https://docs.maylee.app/api-reference/auto-forward-rules/list-auto-forward-rules.md): `GET /auto-forward-rules`
  - [Get an auto-forward rule](https://docs.maylee.app/api-reference/auto-forward-rules/get-auto-forward-rule.md): `GET /auto-forward-rules/{ruleId}`
  - [List the forwarding attempts of a rule](https://docs.maylee.app/api-reference/auto-forward-rules/list-auto-forward-rule-logs.md): `GET /auto-forward-rules/{ruleId}/logs`. The 50 most recent attempts, newest first, with the email that triggered each one.
  - [Create an auto-forward rule](https://docs.maylee.app/api-reference/auto-forward-rules/create-auto-forward-rule.md): `POST /auto-forward-rules`. Forwards every incoming email matching the condition to `forwardTo`.
  - [Update an auto-forward rule](https://docs.maylee.app/api-reference/auto-forward-rules/update-auto-forward-rule.md): `PATCH /auto-forward-rules/{ruleId}`. Requires `allowOutboundSend` on the key.
  - [Delete an auto-forward rule](https://docs.maylee.app/api-reference/auto-forward-rules/delete-auto-forward-rule.md): `DELETE /auto-forward-rules/{ruleId}`. Requires `allowOutboundSend` on the key.

## MCP server

- [MCP server](https://docs.maylee.app/mcp.md): Connect Claude, ChatGPT, Cursor, Claude Code, VS Code or any MCP client to a Maylee workspace to read, triage and draft email, and send it only when you approve.
- [Connect](https://docs.maylee.app/mcp/connect.md): Add the Maylee MCP server to Claude, ChatGPT, Claude Code, Cursor, VS Code or any MCP client, with OAuth or an API key.
- [Permissions and safety](https://docs.maylee.app/mcp/permissions.md): The read, write and send permissions of an MCP connection, the confirmations the assistant must ask for, and the limits that bound what it can do.
- [Tools reference](https://docs.maylee.app/mcp/tools.md): Every tool of the Maylee MCP server, grouped by toolset, generated from the server's own tool definitions.
  - [Reference tools](https://docs.maylee.app/mcp/tools/reference.md): The get_reference tool, which returns label colors, view icons, the filter grammar, rule options, limits and safety rules for the other tools.
  - [Account tools](https://docs.maylee.app/mcp/tools/account.md): Workspace and connection, mailboxes, sync, unread counts, contacts, reply reminders, notification settings and timezone.
  - [Email tools](https://docs.maylee.app/mcp/tools/emails.md): List, search and read emails, conversations and attachments; mark read, pin, move, trash and label; waiting for reply; unsubscribe.
  - [Compose tools](https://docs.maylee.app/mcp/tools/compose.md): Drafts, replies, forwards, sending and scheduling, attachments, automatic replies, Magic Reply, signatures and snippets.
  - [Configuration tools](https://docs.maylee.app/mcp/tools/config.md): Labels, AI label rules, views, inbox filters and auto-forward rules.
- [Reference data](https://docs.maylee.app/mcp/reference-data.md): Label colors, view icons, the filter grammar, AI label rule and auto-forward options, icon names, folders and scheduling rules used by the MCP tools.
- [Limits and troubleshooting](https://docs.maylee.app/mcp/limits.md): Quotas shared with the REST API, hourly safety budgets, response sizes, known limits of the MCP server, and what each error means.

## Webhooks

- [Webhooks](https://docs.maylee.app/webhooks.md): Coming soon. The events Maylee will deliver to your endpoint, their payloads, and how to verify their signature.

## Optional

- [Full documentation](https://docs.maylee.app/llms-full.txt): every page of this site in one Markdown file, API reference and MCP tools included.
- [OpenAPI specification](https://docs.maylee.app/openapi.json): the machine-readable reference of the REST API (OpenAPI 3.1).