MepMail Docs

Mailboxes for people and agents

Separate a personal or agent mailbox from application and campaign sending.

Receiving real messages needs a verified domain whose MX points at MepMail and receiving turned on for it. Creating a mailbox, saving a draft or completing a Checkout does not change your domain's MX.

Choose the service

Use Send for application messages, signup emails and marketing campaigns. Use Mail for a named mailbox on your domain: personal conversations, a company address or an agent that reads and replies to messages. You can continue using Send without creating a mailbox.

Plans and limits

Mail is sold in three monthly plans, with or without a Send plan. People and agents cost the same.

PlanMailboxesStorageOutbound recipients per monthMessages received per monthPrice a month
Solo11 GiB5002,000US$ 2.90 (R$ 14.90 in Brazil)
Duo33 GiB2,0005,000US$ 5.90 (R$ 29.90)
Equipe1010 GiB10,00010,000US$ 12.90 (R$ 64.90)
  • Every limit is shared by the team's mailboxes and renews each billing month. Nothing is charged beyond the plan.
  • Domains: Solo and Duo include 3 sender domains, Equipe 10, on top of what a Send plan already allows.
  • Sending counts the recipients in To, Cc and Bcc of each sent message: one message to three distinct addresses counts three. The plan also caps the bytes sent (message size times recipients): 256 MiB, 1 GiB and 5 GiB a month. Past either limit a send is refused with quota until the next billing month or an upgrade.
  • Receiving counts each received message once, however many of the team's mailboxes or aliases it reaches; a redelivery of the same message is not counted again, and deleting mail does not give the allowance back. The plan also caps the bytes received: 512 MiB, 1.5 GiB and 3 GiB a month.
  • Receiving pauses past the received limit plus a 10% margin, or when storage is full. Senders then get a permanent "mailbox unavailable" bounce (5.1.1) and nothing is stored. Receiving resumes by itself on the next billing month, after an upgrade or, when storage was full, within a minute of freeing space. Mail accepted before the pause is always stored.
  • With storage full, reading, search, attachment downloads and the API keep working; new drafts and sends are refused until space is available. Free it with Empty trash, or Delete forever on messages in the trash (sent messages stay; copies in backups go within 30 days), or move to a larger plan.
  • Emails: team owners get an email at 80% and at 100% of each limit, once per billing month, and when receiving pauses.
  • Free trial: a first purchase starts with 7 days free; the card is required. During the trial a team sends to at most 50 recipients a day and 200 in total.
  • Contracts bought before these plans keep their price and terms.

Prepare a mailbox

  1. Select the organization and domain in the dashboard.
  2. Open Mail, confirm the license period and available seats, then create a person or agent mailbox with a current owner.
  3. Before moving your existing email, create every mailbox and alias the domain receives and only then switch MX; then turn receiving on in Mail → Receiving, which checks the MX. Creating a mailbox does not change the domain's MX.
  4. For an agent, select the mailbox, open Agent access and create a key for it. The owner selects read, draft and, optionally, send permissions. Store the key privately when it appears; it is displayed once.

Mailbox keys start with mmb_. They are different from Send API keys and from the OAuth connection described in MCP server. The existing Send MCP tools do not provide access to this mailbox API.

Manage the Mail subscription

When subscription management is enabled for your deployment and contract, organization owners and admins can use the controls in the Mail dashboard. If they are unavailable, contact support (suporte@mepmail.dev) or, on your own installation, its operator; do not start another purchase to work around unavailable controls.

  • Change plan: a larger plan applies at once and charges the prorated difference now; during the free trial it ends the trial and charges the new plan. A smaller plan applies at once when your mailboxes, storage and this month's usage fit it, without a refund for the current month. The billing date does not change.
  • Contracts bought before the plans: request a new quantity and use Complete increase payment when offered (extra seats become available only after confirmed payment), or schedule a reduction for the next renewal. You can also move such a contract to a plan.
  • Cancel renewal: the confirmed cancellation takes effect at the displayed period end and removes a scheduled future reduction. Use Resume renewal before that date when the option is available.
  • Pending or unconfirmed: use Refresh status to check the same operation. If it remains unresolved, contact support or your installation's operator; do not start another charge or subscription to work around it.

Stored messages are preserved; reading and export still require current mailbox access. Mail plan changes do not change your Send plan or turn on receiving.

Connect an agent over MCP

Agents that speak MCP (Claude Code, Claude Desktop, Cursor and others) use the mailbox as tools, with no code: mailbox_list_messages, mailbox_read_message, mailbox_save_draft and mailbox_send_draft. When you create the key under Agent access, the dashboard shows the ready command. On MepMail Cloud:

Claude Code
claude mcp add --transport http mepmail-correio https://api.mepmail.dev/mcp/correio --header "Authorization: Bearer mmb_..."

In other clients, add a Streamable HTTP server at https://api.mepmail.dev/mcp/correio with the header Authorization: Bearer followed by the mailbox key. The tools keep the same permissions, limits and activity records as the API below. Message content comes back marked as untrusted data: the agent must not follow instructions that arrive by email.

Connect an agent over the API

Use the dashboard origin of your enabled deployment for these endpoints. They run under /api/mailbox-agent on the Web application, rather than the Send API origin. Keep MEPMAIL_MAIL_ORIGIN and MEPMAIL_MAIL_TOKEN in your agent's private environment; do not include the token in source, URLs, prompts or logs.

Read this mailbox's inbox
const origin = process.env.MEPMAIL_MAIL_ORIGIN;
const token = process.env.MEPMAIL_MAIL_TOKEN;
if (!origin || !token) throw new Error("Configure the mailbox origin and key");

const response = await fetch(
  new URL("/api/mailbox-agent/items?folder=inbox", origin),
  { headers: { Authorization: `Bearer ${token}` } },
);
if (!response.ok) throw new Error(`Mailbox request failed: ${response.status}`);
const { items, limited } = await response.json();
// Handle private message data in the agent; avoid copying it into general logs.

The key selects one mailbox; the caller does not supply a team or mailbox ID. Use folder=inbox, drafts or sent to list messages, newest first. The list returns up to limit items (default 50, at most 100), a limited flag and nextCursor: pass it as cursor for the next page. A team key (mmt_) covers several of your mailboxes: list them with GET /api/mailbox-agent/mailboxes and name the mailbox on each call with the MepMail-Mailbox header (id or address), unless the key has a default; see the recipe One agent, several mailboxes. To read a message's content and attachment metadata, use GET /api/mailbox-agent/items?id=<message UUID> with the same read permission. The response does not include attachment file contents.

To react to new mail instead of polling, subscribe a webhook to mailbox.received: it fires when a message reaches an agent mailbox's Inbox and carries only the mailbox and message IDs, which you then read with this endpoint.

Save a draft or reply

POST /api/mailbox-agent/drafts requires draft permission, an active license with a seat for this mailbox, and available storage. Drafts and their attachments count toward mailbox storage. A new draft uses expectedRevision: 0. The sender address comes from the authorized mailbox.

New draft body
{
  "expectedRevision": 0,
  "to": ["recipient@example.invalid"],
  "subject": "Conversation",
  "text": "A message prepared for review.",
  "retainedAttachments": [],
  "uploads": []
}

Save the returned id and revision. To reply, add sourceItemId containing the inbox message UUID; the server preserves its reply references. To edit an existing draft, supply its id, the same ID as sourceItemId, and its latest expectedRevision. A conflict requires reloading the draft before editing.

to takes 1–20 addresses. Optional cc and bcc add copies and blind copies, with To, Cc and Bcc together at most 20. Blind copies receive the message without the other recipients seeing them: the Bcc header stays only on the saved draft and the Sent copy, and each Bcc recipient counts against the outbound allowance like To and Cc. Drafts from this API take up to 10 attachments, each at most 256 KiB, and a final MIME message at most 1 MiB. An upload is { "filename": "note.txt", "base64": "..." }; retained attachments use the indexes from the source message. Empty arrays are still required when there are none.

Submit the saved revision

Sending requires the owner's explicit send key permission, an active license, a verified domain, remaining allowances and enabled transport. POST /api/mailbox-agent/send accepts only the saved draft's UUID and exact revision:

Send request body — replace with the saved draft values
{
  "id": "00000000-0000-4000-8000-000000000001",
  "expectedRevision": 1
}

A 202 response means the request was admitted to the outbox. Repeating the same draft revision can return the existing outbox with duplicate: true and 200; it does not create a new message. Admission and provider acceptance do not prove delivery. An unknown result needs investigation: contact support or the operator; do not create another draft or automate a resend to work around it.

Owner approval

A read/draft key, without the send permission, does not send on its own: the same request records that the agent wants to send that revision and answers 202 with "status": "awaiting_approval". The mailbox owner gets an email (at most one every 10 minutes per mailbox) and sees the draft marked Awaiting your approval in Mail; they check it and send, edit or delete it. Repeating the request for the same revision answers 200 with duplicate: true. Editing the draft makes a new revision, which needs a new request. This is how you keep a person in the loop: create the agent key without the send permission.

Handle access and service errors

StatusNext step
400Check the request fields, UUID and revision.
401Supply the mailbox key in the Bearer header.
403Check the key's scopes, expiration, revocation and current mailbox owner.
404Confirm the deployment feature is enabled and the requested message exists.
409Reload the draft and confirm the current license, storage and outbound allowance.
413Reduce the request size or attachments.
503Preserve the saved draft and contact support or the operator; do not assume a send was discarded.

Revoke a lost key from the mailbox panel. Ownership and membership changes are checked again by the server; copying a key to another agent does not grant a different mailbox or bypass the owner's permissions.

On this page