Repository navigation
0.5.0
Breaking changes
This release changes the contract in these places. Each is described in full under Changed below.
- Errors: what an account lacks answers
501 not_supportedon every account, before the provider is asked. It answered409,400or404before, and a role without a folder answered404or409. - Errors: a provider's
403answersprovider_erroron every account, a JMAP server's too, also for a JMAP method errorforbidden. JMAP's400and409answerbad_requestandconflict. - Accounts:
PATCH /v1/accounts/{account_id}with settings that name a new server needs every credential of the account in the same request. - Accounts: the capabilities are finer, one per thing they guard.
flagsis gone,stable_ids,deltaandserver_searchleft the API. A client that checks the values strictly fails on the new ones. - Accounts:
operationsinGET /v1/meleaves out what the account cannot do. - Messages:
dateis the Date header on every account, and the new fieldreceivedis when the account received the mail. Lists sort, filter and merge byreceived. - Lists: a list without a folder is the inbox on every account. The role
alllists every folder except the trash and junk. A cursor of a list without a folder handed out before is refused once. - Keywords: keywords keep the provider's spelling and compare without case. Notes a server keeps for itself, such as
$hasattachment, leavekeywords.
The database moves from schema 19 to 22 at the first start. Make a backup before the update: a version before 0.5.0 cannot open the database afterwards.
Added
- The MCP server asks what its token may do every
MAILBOX_MCP_RIGHTS_SECONDS, 60 by default, and when a tool is
refused with403 forbidden, a right missing, at most every five
seconds. With0it asks only at start.
When its tools change it tells its clients with
notifications/tools/list_changedand announcestools.listChanged,
so a right granted or taken away shows without a restart. When the
service refuses the token, every tool goes away, also when a tool is
refused with401. A user that may do nothing keepslist_accounts
alone, which lists no account. A refused token is asked
for no more, since each refusal counts against the address, and a new
one needs a restart. POST /v1/accounts/{account_id}/messages/{message_id}/attachments/{attachment_id}/links
(share_attachment) makes a link to an attachment for another
service, which fetches the file itself withGET /v1/links/{secret}:
once, without a token, untilexpires_at. A link holds
MAILBOX_SERVICE_LINK_SECONDS, 120 by default, andexpires_inasks
for fewer. It needs an API token and the new groupmail.share, which
is in no role template. When the link is used, its token must still
act and holdget_attachmentandshare_attachmenton the message.
Every refusal answers the same404and counts against the client
address as a wrong token does. The audit keepsmailbox.link_shared
andmailbox.link_used, never the secret or the URL. When the mail
server fails to
hand out the file, the link holds for the rest of its time, the answer
is502 provider_unavailableto try again, the audit says
mailbox.link_returned, and the address that asked counts no
failure. Whoever holds the URL fetches the
file. The service logs its path masked, but a reverse proxy in front
writes the whole URL into its access log, where it opens the file
until the link is used or ends. The Python client has
share_attachment, the MCP server a tool of the same name. The tool
is not marked read-only, andlist_accountsnamesshareas a kind
of its own. The database moves to schema 22.- An account answers
operations, inGET /v1/accounts/{id}, the list
andGET /v1/me: the operations the caller can run there, its rights
and what the account can do together, by their names in the catalogue
of rights. A client offers what is in it and needs no knowledge of
providers. The Python client reads it asAccount.operations. - The connect page of the UI offers one form per kind of account to
set up by hand, IMAP, POP3 and JMAP, each with what to know of it.
The forms follow from each kind's description of its connection. - The MCP server shows a mail's marks in words, such as
answered,
apart from its keywords, and its tools name no provider. - A send of a reply or a forward answers
original_marked: whether the
original carries$answeredor$forwardednow. False where the
account does not write that mark, as on Gmail, or the mark failed. - A Microsoft account reads and writes
$answeredand$forwarded, as
the verb Outlook last carried out on a message, so Outlook shows a
reply or a forward of the service too. One of the two at a time, as
Outlook keeps it. Itsmarksname both. A change Exchange refuses as
a conflict right after another one is tried again after a pause. PATCH .../messages/{id}and a batchupdatetakeadd_keywordsand
remove_keywords, which change the keywords a message has instead of
replacing them, andadd_folder_idsandremove_folder_ids, which
put a message into folders and take it out of them where it can be in
several, such as Gmail's labels. Each goes beside the list it changes,
not with it. A message keeps one folder at least.- A draft and a message to send take
attachments_from: attachments of
other messages of the same account by message and attachment id,
attached as they are. It needs the right to read that mail. /v1/mesays per account itsstatus, whether it needsattention
and when its last sync succeeded (last_sync_at).- An account and the accounts of
/v1/mecarrymarks: the marks of
RFC 8621, such as$answeredor$junk, it reads (marks.read) and
those it writes (marks.written). Setting or taking off a mark it
does not write answers501. The Python client has them asMarks. - Messages of IMAP accounts carry a
thread_id. The service threads
them itself, across folders, byMessage-ID,In-Reply-Toand
References. Mail already known is threaded over the next sync
passes. A message that ties two threads together merges the younger
into the older, whose messages show as updated in the change feed.
Every kind of account but POP3 has the capabilitythreads: Gmail,
JMAP and Microsoft keep the threads themselves.
MAILBOX_SERVICE_THREAD_REFERENCES(20) sets how many of the
Referencesof a message count. The database moves to schema 20. GET /v1/accounts/{account_id}/threads/{thread_id}(get_thread)
answers a thread with its messages in every folder, oldest first. A
longer thread lists its newestMAILBOX_SERVICE_THREAD_MESSAGES(500)
and saystruncated.GET /v1/accounts/{account_id}/threads
(list_threads) answers the threads of afolder, each where its
newest message in the folder is, with that message's subject, date
and snippet. Both are inmail.read, and a grant
that names folders sees the messages of a thread in them. POP3 answers
501. The Python client haslist_threadsandget_thread.- The UI lists a folder by conversations where the account keeps
threads, shows a conversation on a page of its own, and names the
others of its conversation below a message. - The MCP server:
- A new tool
get_threadreads a conversation in every folder,
oldest first, from a mail of it such as a search hit or from its
thread id. The newest 20 mails come as plain text and share
max_chars. Search results andget_messagename the thread of
a mail. update_messagesadds and takes off keywords and labels
(add_folders,remove_folders,add_keywords,
remove_keywords). At Gmail it labels a mail and leaves it in the
inbox.send_message,create_draftandupdate_drafttakequote,
forward_as,reply_to,attachmentsas base64 and
attach_from, attachments of other mail of the account.- A new tool
update_folderrenames and moves a folder. list_accountsnames an account that needs a person, and why.- Search results and
get_messagename the folders and keywords of a
mail.get_messagenames the mail a draft answers.
- A new tool
Changed
- Breaking: a provider that refuses a request with
403answers
provider_erroron every kind of account: the server took the
credential and refused the request. A JMAP server's403answered
provider_auth_failedand marked the account as needing a new
sign-in. The same holds for a JMAP method errorforbidden, as from
a read-only token. A JMAP server's400and409answer
bad_requestandconflict, as Gmail's and Microsoft's do. - Breaking:
PATCH /v1/accounts/{account_id}with settings that
name a new server needs every credential of the account in the same
request, else it answers400. A server removed needs none. The UI
says so under the password of an account. benethos-mailbox-mcprequires mcp 2.3 and uvicorn 0.38 at least,
the versions the workspace and the service already ask for.- Breaking:
operationsof an account inGET /v1/meleaves out
what the account cannot do, such aslist_threadson POP3. It named
the caller's rights alone. - Breaking: the capabilities of an account are finer, each guarding
one thing:read_state,stars,keywords,folders,move,
trash,purge,labels,search,drafts,send,sent_copy,
threads,push,external_changesandrefused.flagsis gone,
andstable_ids,deltaandserver_searchleft the API. A client
that checks the values strictly fails on the new ones. - Breaking: what an account lacks answers
501 not_supported, the
same on every account, before the provider is asked: a send without
an SMTP server, a draft without a drafts folder and a delete without a
trash answered409, several folders withoutlabels400. A
change with something the account lacks changes nothing, also where
the rest of it would work. - Breaking:
dateis the message's Date header on every account,
the time its sender wrote it. Microsoft answered the received time,
and Gmail and JMAP the received time where a mail had no Date header,
which is now null. A new fieldreceivedsays when the account
received the message: INTERNALDATE on IMAP, the topmostReceived
header on POP3. Lists sort by it,afterandbeforecompare it, and
the list across accounts merges by it. - Breaking: a list without a folder is the inbox on every account.
It was every folder on Gmail, Microsoft and JMAP, the trash and junk
among them. The rolealllists every folder but the trash and junk.
Where the account has such a folder, Gmail's All Mail or a JMAP or
IMAP server's own, that folder isall. On Microsoft, and on JMAP and
IMAP without one, the service shows a folder "All Mail" with that
role. A grant narrowed to folders listsallwithin them. The list across
accounts takes the inbox withoutfolderas well. A cursor of a list
without a folder handed out before this version is refused once. - Breaking: a role the account has no folder for answers
501 not_supported, in a list, a move or as a parent, and names the
account inincompleteacross accounts. It answered404, and an
adapter409. - An IMAP server without a folder
\Allgets one from the service:
"All Mail", with the idalland the roleall. It lists every
folder but the trash and junk, one SEARCH per folder, newest first by
when the mail arrived. A mail filed late with an old date can come on
a later page than its date says, never twice or not at all. A message
cannot be moved into it. has_attachmentsin a list counts real attachments as a whole
message does, not an image the body shows: IMAP reads BODYSTRUCTURE
with the headers, Gmail the parts of a message, JMAP its attachments.
A list guessed from the header before (multipart/mixed). A POP3 list
still guesses, since it reads the headers alone.- Breaking: keywords keep the provider's spelling, such as an
Outlook categoryWork, and compare without case. They came in lower
case. The marks keep the spelling of RFC 8621, such as$answered.
A keyword may hold spaces and other characters, on one line and up to
100 characters, so an Outlook category goes back as it came. IMAP and
JMAP keep atoms only and answer anything else with400. - Breaking: notes a server keeps for itself leave
keywords:
$hasattachment,$hasnoattachment,$mdnsent,$submitpending
and$submitted. A change of the keywords leaves them on the message. - An account's capabilities follow from what its server answers, asked
when it is connected or verified, when a folder comes or goes, and
when the server refuses what they promised. They are stored with the
account and answered while its server cannot be reached. The database
moves to schema 21. An account connected before is asked once when
the service takes it up. - After a reply or a forward the service adds
$answeredor
$forwardedto the original instead of writing its keywords anew, so
a keyword another client set meanwhile stays. - The Claude Desktop extension and the registry entry say that the
setting for plain http is not needed for localhost or https. - The images of the service and the MCP server run on Python 3.15.
Fixed
GET /v1/accounts/{account_id}/messagesfor a grant that names
folders asks the mail server for the account's folders once. It asked
up to three times, with the folderallor a role.- A message id that the index still holds but the server no longer
finds starts one sync pass of its account until the next pass, not
one per request. - An operation the server refuses with
501although the account's
abilities let it pass asks the server what it can do once a minute
at most. A client that asked again and again made a round trip to
the mail server each time. GET /v1/changeswithsinceanswers for a grant that names
folders also while one of its accounts does not answer. One account
down failed the whole request. The page ends before that account's
first change of a message, withstatebefore it, and that change
comes once the account answers again. A webhook of such a grant
waits there too. Webhooks left those changes out for good.- A reply joins the thread of the mail it answers also where its
In-Reply-Toholds a comment beside the id, or itsReferences
are folded inside an id. The ids are read between their angle
brackets. GET /v1/accounts/{account_id}/threadsshows each thread once, page
by page. In the folderalla thread came again on later pages, as
in the UI's conversations of All Mail, and so did one whose messages
came in the same second at the end of a page. A cursor of the list
made before is refused once. Where a folder does not list by date,
as IMAP lists a mail moved into it last, no thread is left out, and
messages of one second over three pages no longer repeat a thread.GET /v1/accounts/{account_id}/threadsof an IMAP account shows a
message the service has no thread for yet as a thread of its own
under the message's id, whichGET .../threads/{thread_id}takes as
well. It was left out until the next sync pass.- A list across accounts,
GET /v1/messages, gives every message once
when a client asks the next page for fewer messages than the one
before. It gave some twice, as the MCP server'ssearch_messages
could. The cursor carries the size the accounts are read in. - The Python client names a charset of an attachment only where it
decodes text.charset=base64came through, and the MCP server's
get_attachmentfailed on it. The MCP server reads a text whose
charset decodes none as UTF-8. - A Gmail account tries a request again, twice at most with a short
pause, when Gmail answers with an error of its own side, such as
500 backendError, as Gmail asks. Only requests that change nothing
more when they run twice are tried again, never a send or a new
draft. Such an error ended the operation at once. - A text part without a file name, not marked as an attachment, is
the body and no longer listed inattachments, also where it carries
a Content-ID. Exchange gives the body one when a large mail's files
are added one by one, so such a mail listed its text as a nameless
attachment. list_threadsanswers501on a POP3 account, asget_threaddoes,
instead of an empty page.- A Gmail draft carries the keyword
$draft, as on the other providers,
andget_messagenames the mail it answers (reference). It was
always null on Gmail. - A Microsoft account answers
501when a change sets or takes off a
mark it does not write, such as$junk, which Outlook keeps no place
for. It answered success and stored nothing. - The
next_cursorof a Microsoft account belongs to its folder and
search, as on the other providers. Sent with another folder or filter,
it answered the first list's next page. Now it answers400 invalid_cursor. A cursor handed out before this version is refused
once. GET /v1/messageswith afolderrole names each account without such
a folder inincomplete, on the first page, asnot_found. It left
them out without a word.- An IMAP folder below one that holds no messages (
\Noselect), which
is not listed, names the nearest listed folder above asparent_id,
or none. It named the unlisted one. Renamed, it stays where it is on
the server. - When Gmail, Microsoft or a JMAP server forgot the state of the last
sync, the mail that arrived since then is reported as
message.created. It was taken as known and never reported. update_draftthat cannot delete the draft it replaces takes the new
one back and answers the error, so one draft stays. Where even that
fails, the error names the new draft. On IMAP withoutUIDPLUSit
answers501before storing anything. It could leave both drafts.- A batch whose connection or login fails after some messages are done
answers those as done and the rest with the failure. It answered only
the failure, though the first messages were changed. A delete for good
on Microsoft that stops in the trash says so. GET /v1/messagesacross accounts no longer skips or repeats a mail of
an IMAP account between pages. IMAP lists by arrival, and an old mail
filed late threw the pages off. Each page is still newest first.- A reply sent or drafted through a Gmail account joins the thread of
the mail it answers, in Gmail and inget_thread. Gmail started a
thread of its own for it, since it threads a reply only when told. get_messageof a Microsoft account answerstext_body,html_body
andin_reply_toas the mail has them, as on the other providers. A
plain text mail hadtext_bodynull and Exchange's HTML in
html_body, andin_reply_towas null on every mail but drafts.get_messageof a Microsoft account lists inline images as
attachments, which can be downloaded. A mail with inline images only
listed none. Attachment ids of Microsoft mail now look like those of
the other providers, such asatt_0. An id handed out before answers
404.- A send through a Microsoft account answers
sent_copy_id, and
message.sentin the change feed names the copy. Both carried the
Message-IDheader before. - A change of an IMAP message that sets flags and moves it, on a server
withoutMOVEandUIDPLUS, answers501before anything changes.
It stored the flags and then refused the move. A move that fails after
the flags were stored says so in its error. - A Microsoft account sends and saves mail above about 3 MB, up to the
25 MiB of attachments the service allows. It answered a provider
error, since Graph takes at most 4 MB per request. Such a mail is
stored without its files, which follow one by one, a large one in
ranges.
Security
- The MCP server's
get_attachmentgives up a PDF whose pages take
longer than 30 seconds to render, and renders one PDF at a time. A
PDF made to take long held the tool without end. - A grant's recipient pattern
*@domainmatches only an address with
one@and a local part. It matcheddomainalone and
a@b@domainas well. - The UI shows a refusal when an account is connected, and one of a
send or a draft, with every secret masked, as every other page
does. A server that echoed a password showed it there. - A sent draft marks the message it answers or forwards only where the
caller may change that message, withupdate_messageand a grant
that reaches its folder. Any client that writes drafts could name a
message there, and the send marked it. - A change or delete of a folder with a role, such as the trash,
answers404to a caller whose grants do not reach it. It answered
409with the folder's name before. - Under
/v1, a request counts against the limit of its client address
unless a valid token counted it. AnyAuthorizationheader took it
off that count before, and another scheme thanBeareror an empty
bearer counted no failure of the address either. Now both count. - A change of an account's settings that names a server it did not
name before, anotherhost,port,smtp_hostorsmtp_port, no
longer tries the stored credentials there. Whoever may change an
account could send its password to a server of their choice. GET /v1/messagesmasks every secret in the message of an account
that failed, inincomplete, as an error answer does.- A cursor of
GET /v1/messagesthat asks for pages above 200, the
largestlimit, is refused with400. An edited cursor made every
account read pages of any size.