Repository navigation
0.3.0 (beta)
The status is beta: usable with real accounts. A breaking change of
the API or the configuration is announced here. Stored data is
carried forward by migrations.
Added
-
benethos-mailbox-client, the Python client of the REST API, as a
package of its own on PyPI:MailboxClientfor async code and
SyncMailboxClientfor code without an event loop, with the same
methods and records. The MCP server is built on it. Its interface has
no stability promise yet. Every error is aMailboxError. An answer it
cannot read, one that is no JSON or lacks a field, is anApiError
with the codeunexpected_response.from_environment()reads
MAILBOX_SERVICE_URL,MAILBOX_SERVICE_TOKENand
MAILBOX_SERVICE_ALLOW_HTTPonce, for a program that makes clients
for a long time. -
Microsoft accounts connect without an app of your own: the service
comes with the project's app, a public client without a secret, used
whenMAILBOX_SERVICE_OAUTH_MICROSOFT_CLIENT_IDis not set. Changing
between it and an app of your own asks every Microsoft account to sign
in again. -
Sign in with a code:
POST /v1/oauth/{provider}/devicereturns a code
to enter at the provider on any device, and
POST /v1/oauth/{provider}/device/{sign_in_id}answers with the
account once the person signed in. It needs no address the provider
sends a browser back to, so it works on a server. The UI offers it
beside the sign-in in the browser, when connecting and on an account's
page. With the project's app away from localhost, it is the only way. -
MAILBOX_SERVICE_PROVIDERS, a JSON list of the kinds of account a
deployment offers, every kind without it. Discovery leaves out the
others, and connecting one answers501. Accounts connected before
keep working. -
JMAP accounts,
"provider": "jmap", for Fastmail, Stalwart, Cyrus and
any JMAP server. The settings namehost,portandpathof the
session (default/.well-known/jmap), andauth:passwordwith
username, ortokenwith the credentialtoken. Everything an IMAP
account does works, sending included, through JMAP without SMTP
settings. Ids stay when a message moves, and a message can be in
several folders (labels). The change feed learns of changes since a
state, and the server's event source wakes the sync. A deleted message
is reported without a folder. A replaced draft gets a new id. -
Discovery asks
https://{domain}/.well-known/jmapand the SRV record
_jmap._tcp, without a credential:jmapis a source, aprovider
of a candidate and aprotocolof a server, whosepathnames the
session. A JMAP candidate comes before IMAP, and POP3 is offered only
where neither is.api_tokenis a newcredential. The Fastmail
preset offers JMAP with an API token. The UI connects a JMAP server
from discovery or by hand, with a password or an API token. -
POP3 accounts,
"provider": "pop3", for mailboxes without IMAP. The
inbox is the one folder. Messages are listed newest first, read and
deleted for good, and sending goes over SMTP. Read state, stars,
keywords, a delete into the trash, search, folders and drafts answer
501. The sync polls the mailbox, so the change feed,whats_newand
webhooks report what arrives and leaves. A server withoutUIDLis
refused. Discovery offers POP3 where it finds no IMAP:pop3is a
providerof a candidate and aprotocolof a server. The UI offers
POP3 when setting up by hand. -
capabilitieson an account and on each account of/v1/me: what it
can do beyond reading its inbox.flags,foldersandsearchare
new. A POP3 account has none of them. The UI offers no action an
account cannot do, and the MCP server'slist_accountsnames what an
account lacks asunsupported. -
containers/production/: Mailbox in operation from the published
images, without a clone of the repository..envnames the version,
the profilehttpsputs Caddy in front with a certificate from Let's
Encrypt. The MCP server is not part of it by default: each client starts
one of its own, with its own token, against the service's address.setup.shdoes the
first start: the master key, the keys, the first administrator. Its
README has the same steps by hand. It keeps the project name
benethos-mailbox, so the data volume of the compose file before
stays: copy itssecrets/master_keyover. -
MCP server instances beside the service in
containers/production/,
for clients that connect over HTTP. Each is a block in
compose.override.yamlthat extendsmcp.yaml, with the profile
mcp, one user's token and a bearer token of its own. It listens on
127.0.0.1, or Caddy routes to it under a path of its own, such as
/mcp/agent, by a file incaddy.d/. -
MAILBOX_TLSincontainers/production/.env: where Caddy's
certificate comes from.acmeis Let's Encrypt as before,internal
Caddy's own CA,filesa certificate of your own insecrets/tls/,
for a network without access from the internet. -
Settings and data in the folders of the operating system, for an
installation without the repository:%LOCALAPPDATA%\benethos-mailbox-service\
withconfiganddataon Windows,~/.config/benethos-mailbox-service/
and~/.local/share/benethos-mailbox-service/on Linux. A file named
with--env-filecomes first, thenconfig/benethos-mailbox-service/
ordata/benethos-mailbox-service/in the working directory, as
before. -
benethos-mailbox-service pathsnames the settings file, the data
folder, the database and where the master key is. -
The MCP server reads an optional
.env:--env-fileor
MAILBOX_MCP_ENV_FILE, elseconfig/benethos-mailbox-mcp/.envin the
working directory, else its config folder of the operating system. The
environment wins over it. -
serviceon users and roles, inPOST,PATCHandPUT: rights of
the service, bound to no account.accounts.connect,users.read,
users.manage,webhooks.manage,audit(below) andadminbelong
there, or single operations of them./v1/permissionslists these
groups asservice. -
accounts.connect:discover_accountandcreate_account, which
were part ofaccounts.manage, and the sign-in with a code. -
users.read:list_users,get_user,list_tokens,list_rolesand
get_role, to see users and roles without changing them.users.manage
keeps every right it had. -
Whoever connects an account gets
accounts.manageon it, unless it
holds that there already. -
expires_aton a grant, with a time zone, null for never. An expired
grant grants nothing and stays until it is removed. A grant is handed
out for no longer than the giver holds it. The editor has a field
"Valid until", and the user's page marks an expired grant. -
/v1/megives each account asendinglist, one entry per grant that
allows sending there: itsrecipients,max_sends_per_dayand
sends_left, how many more the limit allows now. -
The MCP server's
list_accountsnames these limits besidesend, and
warns of an account where the token may read mail and send it anywhere. -
The UI's New role page offers four templates that fill the form:
Reader, Agent, Sender and Operator. -
folderson a grant: reading, writing and deleting mail only in these
folders and their subfolders, named by role, name or id. A message or
folder outside answers404, a move or a new folder outside403.
Deleting to the trash stays allowed, reading the trash needs it in the
list. Folder lists, message lists, the change feed and webhooks leave
out the rest, and a reply or forward needs its original in reach. The
editor has a field "Only in the folders". -
GET /v1/audit(list_activity): the audit of administration, newest
first. Sign-ins, failed ones and refused tokens, and who changed users,
passwords, tokens, roles, accounts and webhooks, with the user, the
credential, the client address, the record touched, the outcome and
what was done. Never a secret, never mail content, and a failed sign-in
with a name that is no user's keeps no name. Filtersuser,
activity(a name or its area),record,after,before. Kept for
MAILBOX_SERVICE_AUDIT_DAYSdays, as the audit of sends. -
auditinservicereads it.auditin a grant stays the audit of
sends./v1/permissionslistsauditamong the groups of the service,
withlist_activityin the group. -
The UI has a page Audit under Service, and a user's page a card Recent
activity, both forauditinservice. -
Filters on the lists, as the UI has them. Each is optional, and a list
without one answers as before.GET /v1/sendsand
GET /v1/accounts/{id}/sends:user,outcome,recipient(part of
an address),afterandbefore(a time with a zone).
GET /v1/users:name(part of it),role,disabled,ui_sign_in.
GET /v1/accounts:address(part of it),provider,status.
GET /v1/webhooks:url(part of it),account,failing. -
A user in the answers of
/v1/userssays how it signs in to the UI:
has_password,must_change(a password set for it, to be changed at
the next sign-in) andlast_sign_in_at. The schema isUserInfo, the
fields ofUserand these three. The user's page in the UI names a
password still to be changed. -
The UI shows a message's keywords in the list and adds or removes them
on the message. Those starting with$stay as they are. -
accountsonGET /v1/sends: the audit of the named accounts alone,
as/v1/messagesand/v1/changestake it. An account the caller
may not audit is left out without a word. -
GET /v1/status(get_status, inaccounts.read): the sync worker
and the accounts the caller may see the status of, as the UI's status
page shows them. Per account its status, the last pass, the last error
and whether it needs a look. Nothing is asked of a provider. The UI's
status page needsget_statustoo, whichaccounts.readholds.
Changed
- Breaking:
POST /v1/oauth/{provider}/startis gone, and with it
the rightstart_oauth. The provider sent the browser back to a page
of the UI, so an API caller could start the sign-in but never finish
it. The API signs an account in with a code
(POST /v1/oauth/{provider}/device), the UI in a browser or with a
code as before. A stored grant namingstart_oauthkeeps its other
rights. - Breaking:
DELETE /v1/users/{user_id}/tokens/{token_id}answers
204without a body, as every other delete does. It answered200
with the token's record. The token stays in
GET /v1/users/{user_id}/tokenswith itsrevoked_at. disabledis no longer a value of an account'sstatus: nothing
ever set it. The values areconnected,needs_reauthand
unreachable.- The OpenAPI document names on each operation the errors it can
answer:413,429and500on every one,404and409where a
record is touched,501and502where a provider is asked. Before,
every operation named the same list, without the first three. - A webhook's body carries text beyond ASCII as UTF-8, not as
\u
escapes. It is the same JSON, and the signature covers the bytes sent. - A cursor of a JMAP account's message list from an earlier version
answers400 invalid cursor: start the list again. - What an account cannot do answers
501 not_supportedwith the same
message for every kind of account, e.g. "this account keeps no
drafts". A change of a POP3 message answers501even when it would
change nothing. - A change and its record in the audit of administration are stored in
one transaction. When the record cannot be written, the change is
undone and the request fails with500. Before, the
change stood and the log saidsystem.not_audited. A user's deletion
now removes its tokens, password, webhooks and the user in one step as
well. backupwrites format 2: the database is encrypted in blocks of 1 MiB
from a copy beside the database, andrestoreandbackup verify
decrypt it block by block. Before, the database was held in memory
twice. Backups of format 1 are still read. A backup of format 2 needs
this version or later to be read.- Rights that do not exist in a stored grant or role, e.g. of an older
version, are logged once per user as the activity
users.unknown_rights, not on every request. - A Microsoft client secret without
MAILBOX_SERVICE_OAUTH_MICROSOFT_CLIENT_IDstops the service: it would
belong to no app. An empty secret counts as none. - The sync worker takes up an account at once when it is connected, its
servers or credential change, or it is verified after a rejected login.
Before, it waited for its next round, 5 minutes by default: a mail that
arrived in between never reached the change feed, and push started
late. - Breaking:
containers/dev/compose.yamlhands the MCP server its
API token asMAILBOX_SERVICE_TOKEN, the name the server reads. The
variableMAILBOX_MCP_API_TOKENis gone. - Breaking:
containers/compose.yamlmoved tocontainers/dev/and
builds from the repository only.MAILBOX_SERVICE_IMAGEand
MAILBOX_MCP_IMAGEare gone: the published images run from
containers/production/. The Dockerfiles are incontainers/images/. - Breaking: a key file in the data folder is refused
(MAILBOX_SERVICE_KEY_FILEbelowMAILBOX_SERVICE_DATA_DIR). A copy
of the folder would carry the key to the credentials with it. Move the
file elsewhere, e.g. into the config folder thatpathsnames. - Breaking:
GET /v1/accountsandGET /v1/usersare paged like
the other lists. They answer{"items": [...], "next_cursor": ...}
instead of an array and takelimit(1 to 200, default 50) and
cursor. Accounts come by address, users by name, both regardless of
case. The filters narrow the list before it is paged. The UI pages
Accounts and Users the same way. - The UI's filters have the API's query names:
useron Sends and
Audit,recipienton Sends. A kept link withwhoortono longer
filters. - Minimum versions without a known vulnerability.
benethos-mailbox-service:
fastapi 0.133.0, starlette 1.3.1 (now named, fastapi asks for no safe
version), python-multipart 0.0.31, cryptography 50, anyio 4.14.2,
jinja2 3.1.6, dnspython 2.6.1.benethos-mailbox-mcp: starlette 1.3.1,
anyio 4.14.2. An install from the lockfile, as the images do, had them
already. - The project is named Mailbox, its packages
mailbox-service,
mailbox-clientandmailbox-mcp. The OpenAPI document's title is
mailbox-service, the MCP server'smailbox-mcp. On PyPI and
ghcr.io the names staybenethos-mailbox-service,
benethos-mailbox-clientandbenethos-mailbox-mcp. - A right of the service or
adminin a grant'sallowanswers400,
and a right on accounts inserviceas well. Stored rights move at the
first start: what a grant named of the service goes toservice, a
grant withaccounts.manageon every account getsaccounts.connect.
Nobody loses a right. The log names each user and role whose rights
moved. accounts.manageis about existing accounts alone:update_account,
delete_accountandverify_account.- On an IMAP server that keeps every folder below the inbox, such as
INBOX.Sent, the folders right below it are at the top, as mail
clients show them:parent_idis null for them. Their ids stay. - A change that would leave no enabled administrator who can sign in to
the UI answers409: disabling, deleting, takingadminor the UI
sign-in away, directly or through a role. Where there is none to begin
with, nothing is held back.users set-passwordon the host stays the
way back.
Fixed
GET /v1/sendsgoes by its own right,list_all_sends, as the lists
of messages and changes across accounts do. A grant naming that one
operation got an empty list, one naminglist_sendsalone got every
account's audit. Grants with the groupauditwere not affected.backup FILE --recovery-keyis refused: the option belongs to
backup verify FILE. Before, it was accepted and ignored, and the
backup written with the master key the service holds.- The days of the filter on the pages Audit and Sends start at midnight
in the local time of the service's machine, the time the pages show.
Before, they started at midnight UTC. - A sign-in with a code survives a provider that is not reached for a
moment: the poll answers502 provider_unavailable, the code stands,
and the next poll waits longer. A token endpoint that answers5xxor
temporarily_unavailableis502 provider_unavailableeverywhere,
not502 provider_error. - The MCP server makes its REST client in its lifespan, one per server.
It reads the service's address and token once, when it starts. - Old records of the audit, the change feed and the audit of sends go
when the service starts. Before, they waited for the first new record
of their kind. - A subject, a display name or a file name of an attachment that holds
a control character is sent with a space in its place, as one with a
line break already was. - A line break in a user name, password or token is refused with
400
before the IMAP or POP3 login: it would have ended the command and
started another. An SMTP address with a blank or a line break is
refused with400. Before, it ended in500. - A quote in a Microsoft search no longer ends its phrase: the rest of
the text could pass for search syntax. - The display name of an account is one line of at most 200 characters,
else400. One stored with a line break made every send fail with
500. It now goes out on one line. - A line break in a name or an address, such as CR LF or U+2028, no
longer starts a line of its own in the log. The log writes it as its
escape. - Connecting an account refuses an address that is none, e.g. without a
domain or with a line break, with400. A host that is neither a
name nor an IP address, e.g.imap.example.org:993, is refused with
400before it is looked up. Before, it ended in502. - The sync worker forgets a deleted account. It kept a note of each one
for as long as the service ran. openapiandkeys generatetake--env-file, before or after the
command, like every other command. They stopped with "unrecognized
arguments".- The audit of administration names the role of a
users.role_deleted
record. Itsrecordwas empty. PUT /v1/accounts/{account_id}/drafts/{draft_id}said the draft keeps
its id. That holds for IMAP only: a Microsoft or JMAP draft is stored
as a new message under a new id, which the answer names. The UI's
"Save" and "Send" on an edited draft used the old id at Microsoft and
JMAP and ended in404, with the draft saved and nothing sent. They
now go on with the new id. The MCP server'supdate_draftsays so.