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.
| Plan | Mailboxes | Storage | Outbound recipients per month | Messages received per month | Price a month |
|---|---|---|---|---|---|
| Solo | 1 | 1 GiB | 500 | 2,000 | US$ 2.90 (R$ 14.90 in Brazil) |
| Duo | 3 | 3 GiB | 2,000 | 5,000 | US$ 5.90 (R$ 29.90) |
| Equipe | 10 | 10 GiB | 10,000 | 10,000 | US$ 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
quotauntil 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
- Select the organization and domain in the dashboard.
- Open Mail, confirm the license period and available seats, then create a person or agent mailbox with a current owner.
- 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.
- 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 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.
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.
{
"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:
{
"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
| Status | Next step |
|---|---|
400 | Check the request fields, UUID and revision. |
401 | Supply the mailbox key in the Bearer header. |
403 | Check the key's scopes, expiration, revocation and current mailbox owner. |
404 | Confirm the deployment feature is enabled and the requested message exists. |
409 | Reload the draft and confirm the current license, storage and outbound allowance. |
413 | Reduce the request size or attachments. |
503 | Preserve 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.
Billing (hosted deployments)
How plans, Stripe Checkout, and the webhook fit together on a hosted MepMail deployment, and how to provision a Stripe account for it.
Recipes
Four end-to-end integrations — a support agent with human approval, triage without send, one agent over several mailboxes, and SaaS notifications — with the right credential, events, errors and diagnosis for each.