Spacemail MCP connects your AI assistant (such as Claude) to your Spacemail mailbox. Through it, the assistant can list your folders, list, search and read your emails, mark them read or as favorites, move them between folders or to Trash, and send, reply to and forward emails from your own address — you ask in plain language, and the assistant calls the right tools.
You need a Spacemail mailbox. Spacemail MCP is available at https://mcp.spacemail.com/mcp.
How you connect depends on your AI assistant:
Claude (web and desktop) — open Settings, choose Connectors, add a custom connector, and point it at https://mcp.spacemail.com/mcp. Anthropic's Claude is the client we have verified Spacemail MCP to work with.
Other MCP clients — add a remote MCP server and point it at https://mcp.spacemail.com/mcp. Other clients may work, but we haven't verified them yet.
When you connect, you'll be asked to sign in and approve the assistant's access to your mailbox. The assistant then acts only on that mailbox, and only through the tools below.
Email content is untrusted. Subjects, senders, previews and bodies are written by other people. Spacemail MCP tells the assistant to treat them as data, not as instructions, but an email can still try to steer it: review what the assistant proposes before you approve a change.
Sent email is real email. email_send, email_reply and email_forward send from your own Spacemail address, and a sent email cannot be called back. The assistant should send only what you asked for: review the recipients and the text before you approve a send.
Plain text only. You write the text of a new email, reply or forward as plain text. You cannot upload attachments, save drafts or send secure messages; a forward can include the attachments of the email it forwards.
Nothing is deleted permanently. Deleting an email moves it to your Trash folder, from where you can move it back. No tool empties Trash or erases a message.
The agreements and policies that apply to Spacemail MCP:
Access: Read only retrieves information. Write changes your mailbox in a way you can change back, or sends an email from your address, which cannot be undone.
Tool: folder_list
What it does: List your folders with their unread and total counts
Access: Read
Tool: email_list
What it does: List the emails in a folder, newest first
Access: Read
Tool: email_search
What it does: Search emails by text, unread, favorite or high priority
Access: Read
Tool: email_read
What it does: Read one email and mark it as read
Access: Write
Tool: email_mark_read
What it does: Mark an email as read or unread
Access: Write
Tool: email_mark_favorite
What it does: Mark an email as a favorite or remove the mark
Access: Write
Tool: email_move
What it does: Move an email to another folder
Access: Write
Tool: email_delete
What it does: Move an email to Trash
Access: Write
Tool: email_send
What it does: Send a new email
Access: Write
Tool: email_reply
What it does: Reply to an email, or reply to all
Access: Write
Tool: email_forward
What it does: Forward an email, with its attachments by default
Access: Write
Every email in a list or search result carries folderFullName and uid. The other tools take these two values as folder and uid. A uid is only valid inside its folder and changes when the email is moved, so after a move the assistant uses the new uid the move returned, or lists the folder again.
The folder Virtual/All covers every folder, including Trash, Spam, Drafts and Sent. It is accepted by email_list and email_search only; each result still carries the real folder of the email.
email_search with unreadOnly: true finds the unread emails across all folders.
email_read opens the ones you ask about; reading marks them as read.
folder_list shows the folders and their exact names.
email_list lists the emails of the folder.
email_move files an email into another folder, or email_delete moves it to Trash.
email_search or email_list finds the email.
email_read shows it to you, so you can decide what to answer.
email_reply sends your answer, or email_forward passes the email on to someone else.
folder_list — List foldersAccess: Read.
Lists the folders of the mailbox as a flat list, nested folders included. Use a folder's fullName as the folder argument of the other tools.
This tool takes no parameters.
{"folders": [{ "fullName": "INBOX", "name": "INBOX", "parentFullName": "", "unread": 3, "total": 120, "role": "inbox" },{ "fullName": "Receipts", "name": "Receipts", "parentFullName": "", "unread": 0, "total": 14, "role": null }]}
role is inbox, sent, drafts, trash, junk or archive when the folder has one, otherwise null.
email_list — List emailsAccess: Read.
Lists the emails of one folder, newest first, one page at a time.
Parameter: folder
Required: Yes
Type & constraints: String, 1–1024 characters: the folder's fullName, or Virtual/All
Parameter: page
Required: No
Type & constraints: Integer ≥ 0, zero-based. Defaults to 0
Parameter: count
Required: No
Type & constraints: Integer 1–100: emails per page. Defaults to 25
{"items": [{"folderFullName": "INBOX","uid": 4821,"from": [{ "name": "Jane Doe", "address": "jane@example.com" }],"to": [{ "name": null, "address": "you@yourdomain.com" }],"subject": "Invoice for October","date": "2026-10-14T09:12:00Z","previewText": "Hi, please find the invoice attached…","isRead": false,"isFavorite": false,"isAnswered": false,"hasAttachments": true,"importance": "Normal"}],"total": 120,"page": 0,"count": 25,"hasMore": true}
email_search — Search emailsAccess: Read.
Searches the emails of a folder by text and filters, one page at a time. Without a folder, it searches Virtual/All.
Parameter: folder
Required: No
Type & constraints: String, 1–1024 characters. Defaults to Virtual/All
Parameter: query
Required: No
Type & constraints: String, 3–255 characters: text to search for
Parameter: unreadOnly
Required: No
Type & constraints: Boolean: only unread emails
Parameter: favoritesOnly
Required: No
Type & constraints: Boolean: only favorite emails
Parameter: highPriorityOnly
Required: No
Type & constraints: Boolean: only high-priority emails
Parameter: page
Required: No
Type & constraints: Integer ≥ 0, zero-based. Defaults to 0
Parameter: count
Required: No
Type & constraints: Integer 1–100: emails per page. Defaults to 25
The result has the same shape as email_list.
email_read — Read emailAccess: Write — reading marks the email as read.
Reads one email: headers, attachment details and the body. The body is the cleaned-up HTML version when the email has one (bodyFormat html), otherwise its plain text (bodyFormat text), cut at 100,000 characters (bodyTruncated). Attachments are listed, not downloaded.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email (its folderFullName), not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer: the email's uid in that folder
{"message": {"folderFullName": "INBOX","uid": 4821,"messageId": "<abc123@example.com>","from": [{ "name": "Jane Doe", "address": "jane@example.com" }],"to": [{ "name": null, "address": "you@yourdomain.com" }],"cc": [],"subject": "Invoice for October","date": "2026-10-14T09:12:00Z","body": "<p>Hi, please find the invoice attached.</p>","bodyFormat": "html","bodyTruncated": false,"attachments": [{ "name": "invoice.pdf", "contentType": "application/pdf", "size": 48213 }],"importance": "Normal"},"markedRead": true}
markedRead is false when the email was returned but marking it as read failed.
email_mark_read — Mark email read or unreadAccess: Write.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email, not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer
Parameter: read
Required: Yes
Type & constraints: Boolean: true marks the email as read, false as unread
{ "folderFullName": "INBOX", "uid": 4821, "isRead": true }
Setting the same state twice is harmless. A uid that is not in the folder is not reported as an error, so the assistant takes uids from a fresh list.
email_mark_favorite — Mark email as favoriteAccess: Write.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email, not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer
Parameter: favorite
Required: Yes
Type & constraints: Boolean: true marks the email as a favorite, false removes the mark
{ "folderFullName": "INBOX", "uid": 4821, "isFavorite": true }
email_move — Move emailAccess: Write.
Moves one email to another folder of the same mailbox. Moving it to the folder it is already in is refused.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email, not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer
Parameter: destinationFolder
Required: Yes
Type & constraints: String: the folder to move the email to, not Virtual/All
{ "previousFolderFullName": "INBOX", "folderFullName": "Receipts", "uid": 77 }
The email gets a new uid in the destination folder. uid is null when the server did not report it; list the destination folder to find the email. A move is never retried automatically: if it could not be confirmed, the assistant lists the folders before trying again.
email_delete — Delete emailAccess: Write.
Moves one email to the Trash folder. The email is not erased and can be moved back; an email that is already in Trash is refused, because the only remaining step would be a permanent delete, which Spacemail MCP never does.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email, not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer
{ "previousFolderFullName": "INBOX", "folderFullName": "Trash", "uid": 912 }
These tools send real email from your own Spacemail address; the sender cannot be changed. The result only says that the mail server accepted the email for delivery, not that it was delivered.
All three share these limits:
Recipients are bare email addresses such as alice@example.com, without display names, at most 50 in total. The same address given twice counts once.
The text (body) is plain text of at most 200,000 characters. Line breaks are kept; it is not sent as HTML.
No attachments can be uploaded, no draft is saved and no secure message is sent.
A send is never repeated blindly. If the mail server did not confirm it (infrastructure.mailcore.outcome-unknown), the email may have been sent anyway: the assistant looks for it in your Sent folder before sending it again.
email_send — Send emailAccess: Write — sends a real email, which cannot be undone.
Sends a new email.
Parameter: to
Required: Yes
Type & constraints: List of 1–50 email addresses
Parameter: cc
Required: No
Type & constraints: List of up to 50 email addresses. Defaults to none
Parameter: bcc
Required: No
Type & constraints: List of up to 50 email addresses, hidden from the other recipients. Defaults to none
Parameter: subject
Required: Yes
Type & constraints: String: a single line of at most 998 characters
Parameter: body
Required: Yes
Type & constraints: String: plain text, at most 200,000 characters
{ "accepted": true }
To, Cc and Bcc together hold at most 50 addresses.
email_reply — Reply to emailAccess: Write — sends a real email, which cannot be undone.
Replies to one email. The subject gets a Re: prefix (never twice), the reply is threaded under the email, and the email is quoted below your text with a header naming its sender. A very long email is quoted up to 100,000 characters and marked as truncated. Replying does not mark the email as read.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email, not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer
Parameter: body
Required: Yes
Type & constraints: String: plain text, at most 200,000 characters
Parameter: replyAll
Required: No
Type & constraints: Boolean: true also replies to the other To and Cc recipients. Defaults to false
{ "accepted": true }
The reply goes to the email's Reply-To address; when there is none, or it names only you, to its sender; when that is you too, as for an email in your Sent folder, to its original To recipients. Your own address is always left out. With replyAll, the other To and Cc recipients of the email are added; your main address is left out, but your aliases are not, so a copy may reach you through one of them. The reply goes to at most 50 recipients.
email_forward — Forward emailAccess: Write — sends a real email, which cannot be undone.
Forwards one email to new recipients. The subject gets a Fwd: prefix (never twice), and the email is quoted below your text with a header naming its sender, up to 100,000 characters. A forward starts a new conversation. Forwarding does not mark the email as read.
Parameter: folder
Required: Yes
Type & constraints: String: the real folder of the email, not Virtual/All
Parameter: uid
Required: Yes
Type & constraints: Positive integer
Parameter: to
Required: Yes
Type & constraints: List of 1–50 email addresses
Parameter: body
Required: Yes
Type & constraints: String: plain text, at most 200,000 characters
Parameter: includeAttachments
Required: No
Type & constraints: Boolean: true forwards the attachments of the email, false only its text. Defaults to true
{ "accepted": true }
When a tool fails, the assistant receives an error with a code, a detail sentence and retryable, which says whether trying again later can help. The errors you may see:
Code: business.email.same-folder
Meaning: The destination is the folder the email is already in
Code: business.email.already-in-trash
Meaning: The email is already in Trash
Code: business.email.trash-folder-not-found
Meaning: The mailbox has no folder marked as Trash
Code: business.email.no-recipient
Meaning: A new email or forward has no recipient
Code: business.email.no-reply-recipient
Meaning: The email names nobody to reply to except you
Code: business.email.too-many-recipients
Meaning: More than 50 recipients in total
Code: business.email.unauthorized
Meaning: The mailbox refused access; reconnect Spacemail MCP
Code: business.mailcore.folder-not-found
Meaning: The folder does not exist; check folder_list
Code: business.mailcore.message-not-found
Meaning: The email is not in that folder; list the folder again
Code: business.mailcore.quota-exceeded
Meaning: The mailbox is full
Code: business.mailcore.invalid-target-folder
Meaning: Emails cannot be moved into that folder, such as Drafts or Sent
Code: infrastructure.mailcore.timeout
Meaning: The mailbox did not answer in time; retryable
Code: infrastructure.mailcore.unavailable
Meaning: The mailbox service is unavailable; retryable
Code: infrastructure.mailcore.outcome-unknown
Meaning: A move or send was not confirmed; list the folders, or look in Sent, before repeating it