Skip to content

0.5.0

Choose a tag to compare

@BeneODev BeneODev released this 17 Oct 07:11
· 117 commits to main since this release
26c5285

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_supported on every account, before the provider is asked. It answered 409, 400 or 404 before, and a role without a folder answered 404 or 409.
  • Errors: a provider's 403 answers provider_error on every account, a JMAP server's too, also for a JMAP method error forbidden. JMAP's 400 and 409 answer bad_request and conflict.
  • 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. flags is gone, stable_ids, delta and server_search left the API. A client that checks the values strictly fails on the new ones.
  • Accounts: operations in GET /v1/me leaves out what the account cannot do.
  • Messages: date is the Date header on every account, and the new field received is when the account received the mail. Lists sort, filter and merge by received.
  • Lists: a list without a folder is the inbox on every account. The role all lists 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, leave keywords.

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 with 403 forbidden, a right missing, at most every five
    seconds. With 0 it asks only at start.
    When its tools change it tells its clients with
    notifications/tools/list_changed and announces tools.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 with 401. A user that may do nothing keeps list_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 with GET /v1/links/{secret}:
    once, without a token, until expires_at. A link holds
    MAILBOX_SERVICE_LINK_SECONDS, 120 by default, and expires_in asks
    for fewer. It needs an API token and the new group mail.share, which
    is in no role template. When the link is used, its token must still
    act and hold get_attachment and share_attachment on the message.
    Every refusal answers the same 404 and counts against the client
    address as a wrong token does. The audit keeps mailbox.link_shared
    and mailbox.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
    is 502 provider_unavailable to 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, and list_accounts names share as a kind
    of its own. The database moves to schema 22.
  • An account answers operations, in GET /v1/accounts/{id}, the list
    and GET /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 as Account.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 $answered or $forwarded now. False where the
    account does not write that mark, as on Gmail, or the mark failed.
  • A Microsoft account reads and writes $answered and $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. Its marks name both. A change Exchange refuses as
    a conflict right after another one is tried again after a pause.
  • PATCH .../messages/{id} and a batch update take add_keywords and
    remove_keywords, which change the keywords a message has instead of
    replacing them, and add_folder_ids and remove_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/me says per account its status, whether it needs attention
    and when its last sync succeeded (last_sync_at).
  • An account and the accounts of /v1/me carry marks: the marks of
    RFC 8621, such as $answered or $junk, it reads (marks.read) and
    those it writes (marks.written). Setting or taking off a mark it
    does not write answers 501. The Python client has them as Marks.
  • Messages of IMAP accounts carry a thread_id. The service threads
    them itself, across folders, by Message-ID, In-Reply-To and
    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 capability threads: Gmail,
    JMAP and Microsoft keep the threads themselves.
    MAILBOX_SERVICE_THREAD_REFERENCES (20) sets how many of the
    References of 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 newest MAILBOX_SERVICE_THREAD_MESSAGES (500)
    and says truncated. GET /v1/accounts/{account_id}/threads
    (list_threads) answers the threads of a folder, each where its
    newest message in the folder is, with that message's subject, date
    and snippet. Both are in mail.read, and a grant
    that names folders sees the messages of a thread in them. POP3 answers
    501. The Python client has list_threads and get_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_thread reads 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 and get_message name the thread of
      a mail.
    • update_messages adds 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_draft and update_draft take quote,
      forward_as, reply_to, attachments as base64 and
      attach_from, attachments of other mail of the account.
    • A new tool update_folder renames and moves a folder.
    • list_accounts names an account that needs a person, and why.
    • Search results and get_message name the folders and keywords of a
      mail. get_message names the mail a draft answers.

Changed

  • Breaking: a provider that refuses a request with 403 answers
    provider_error on every kind of account: the server took the
    credential and refused the request. A JMAP server's 403 answered
    provider_auth_failed and marked the account as needing a new
    sign-in. The same holds for a JMAP method error forbidden, as from
    a read-only token. A JMAP server's 400 and 409 answer
    bad_request and conflict, 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 answers 400. A server removed needs none. The UI
    says so under the password of an account.
  • benethos-mailbox-mcp requires mcp 2.3 and uvicorn 0.38 at least,
    the versions the workspace and the service already ask for.
  • Breaking: operations of an account in GET /v1/me leaves out
    what the account cannot do, such as list_threads on 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_changes and refused. flags is gone,
    and stable_ids, delta and server_search left 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 answered 409, several folders without labels 400. A
    change with something the account lacks changes nothing, also where
    the rest of it would work.
  • Breaking: date is 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 field received says when the account
    received the message: INTERNALDATE on IMAP, the topmost Received
    header on POP3. Lists sort by it, after and before compare 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 role all lists 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 is all. On Microsoft, and on JMAP and
    IMAP without one, the service shows a folder "All Mail" with that
    role. A grant narrowed to folders lists all within them. The list across
    accounts takes the inbox without folder as 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 in incomplete across accounts. It answered 404, and an
    adapter 409.
  • An IMAP server without a folder \All gets one from the service:
    "All Mail", with the id all and the role all. 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_attachments in 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 category Work, 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 with 400.
  • 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 $answered or
    $forwarded to 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}/messages for a grant that names
    folders asks the mail server for the account's folders once. It asked
    up to three times, with the folder all or 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 501 although 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/changes with since answers 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, with state before 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-To holds a comment beside the id, or its References
    are folded inside an id. The ids are read between their angle
    brackets.
  • GET /v1/accounts/{account_id}/threads shows each thread once, page
    by page. In the folder all a 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}/threads of an IMAP account shows a
    message the service has no thread for yet as a thread of its own
    under the message's id, which GET .../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's search_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=base64 came through, and the MCP server's
    get_attachment failed 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 in attachments, 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_threads answers 501 on a POP3 account, as get_thread does,
    instead of an empty page.
  • A Gmail draft carries the keyword $draft, as on the other providers,
    and get_message names the mail it answers (reference). It was
    always null on Gmail.
  • A Microsoft account answers 501 when 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_cursor of 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 answers 400 invalid_cursor. A cursor handed out before this version is refused
    once.
  • GET /v1/messages with a folder role names each account without such
    a folder in incomplete, on the first page, as not_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 as parent_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_draft that 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 without UIDPLUS it
    answers 501 before 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/messages across 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 in get_thread. Gmail started a
    thread of its own for it, since it threads a reply only when told.
  • get_message of a Microsoft account answers text_body, html_body
    and in_reply_to as the mail has them, as on the other providers. A
    plain text mail had text_body null and Exchange's HTML in
    html_body, and in_reply_to was null on every mail but drafts.
  • get_message of 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 as att_0. An id handed out before answers
    404.
  • A send through a Microsoft account answers sent_copy_id, and
    message.sent in the change feed names the copy. Both carried the
    Message-ID header before.
  • A change of an IMAP message that sets flags and moves it, on a server
    without MOVE and UIDPLUS, answers 501 before 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_attachment gives 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 *@domain matches only an address with
    one @ and a local part. It matched domain alone and
    a@b@domain as 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, with update_message and 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,
    answers 404 to a caller whose grants do not reach it. It answered
    409 with the folder's name before.
  • Under /v1, a request counts against the limit of its client address
    unless a valid token counted it. Any Authorization header took it
    off that count before, and another scheme than Bearer or 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, another host, port, smtp_host or smtp_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/messages masks every secret in the message of an account
    that failed, in incomplete, as an error answer does.
  • A cursor of GET /v1/messages that asks for pages above 200, the
    largest limit, is refused with 400. An edited cursor made every
    account read pages of any size.