Skip to content

0.3.0 (beta)

Choose a tag to compare

@BeneODev BeneODev released this 07 Oct 21:27
· 198 commits to main since this release
96c8a22

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: MailboxClient for async code and
    SyncMailboxClient for 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 a MailboxError. An answer it
    cannot read, one that is no JSON or lacks a field, is an ApiError
    with the code unexpected_response. from_environment() reads
    MAILBOX_SERVICE_URL, MAILBOX_SERVICE_TOKEN and
    MAILBOX_SERVICE_ALLOW_HTTP once, 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
    when MAILBOX_SERVICE_OAUTH_MICROSOFT_CLIENT_ID is 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}/device returns 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 answers 501. Accounts connected before
    keep working.

  • JMAP accounts, "provider": "jmap", for Fastmail, Stalwart, Cyrus and
    any JMAP server. The settings name host, port and path of the
    session (default /.well-known/jmap), and auth: password with
    username, or token with the credential token. 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/jmap and the SRV record
    _jmap._tcp, without a credential: jmap is a source, a provider
    of a candidate and a protocol of a server, whose path names the
    session. A JMAP candidate comes before IMAP, and POP3 is offered only
    where neither is. api_token is a new credential. 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_new and
    webhooks report what arrives and leaves. A server without UIDL is
    refused. Discovery offers POP3 where it finds no IMAP: pop3 is a
    provider of a candidate and a protocol of a server. The UI offers
    POP3 when setting up by hand.

  • capabilities on an account and on each account of /v1/me: what it
    can do beyond reading its inbox. flags, folders and search are
    new. A POP3 account has none of them. The UI offers no action an
    account cannot do, and the MCP server's list_accounts names what an
    account lacks as unsupported.

  • containers/production/: Mailbox in operation from the published
    images, without a clone of the repository. .env names the version,
    the profile https puts 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.sh does 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 its secrets/master_key over.

  • MCP server instances beside the service in containers/production/,
    for clients that connect over HTTP. Each is a block in
    compose.override.yaml that extends mcp.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 in caddy.d/.

  • MAILBOX_TLS in containers/production/.env: where Caddy's
    certificate comes from. acme is Let's Encrypt as before, internal
    Caddy's own CA, files a certificate of your own in secrets/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\
    with config and data on Windows, ~/.config/benethos-mailbox-service/
    and ~/.local/share/benethos-mailbox-service/ on Linux. A file named
    with --env-file comes first, then config/benethos-mailbox-service/
    or data/benethos-mailbox-service/ in the working directory, as
    before.

  • benethos-mailbox-service paths names the settings file, the data
    folder, the database and where the master key is.

  • The MCP server reads an optional .env: --env-file or
    MAILBOX_MCP_ENV_FILE, else config/benethos-mailbox-mcp/.env in the
    working directory, else its config folder of the operating system. The
    environment wins over it.

  • service on users and roles, in POST, PATCH and PUT: rights of
    the service, bound to no account. accounts.connect, users.read,
    users.manage, webhooks.manage, audit (below) and admin belong
    there, or single operations of them. /v1/permissions lists these
    groups as service.

  • accounts.connect: discover_account and create_account, which
    were part of accounts.manage, and the sign-in with a code.

  • users.read: list_users, get_user, list_tokens, list_roles and
    get_role, to see users and roles without changing them. users.manage
    keeps every right it had.

  • Whoever connects an account gets accounts.manage on it, unless it
    holds that there already.

  • expires_at on 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/me gives each account a sending list, one entry per grant that
    allows sending there: its recipients, max_sends_per_day and
    sends_left, how many more the limit allows now.

  • The MCP server's list_accounts names these limits beside send, 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.

  • folders on 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 answers 404, a move or a new folder outside 403.
    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. Filters user,
    activity (a name or its area), record, after, before. Kept for
    MAILBOX_SERVICE_AUDIT_DAYS days, as the audit of sends.

  • audit in service reads it. audit in a grant stays the audit of
    sends. /v1/permissions lists audit among the groups of the service,
    with list_activity in the group.

  • The UI has a page Audit under Service, and a user's page a card Recent
    activity, both for audit in service.

  • Filters on the lists, as the UI has them. Each is optional, and a list
    without one answers as before. GET /v1/sends and
    GET /v1/accounts/{id}/sends: user, outcome, recipient (part of
    an address), after and before (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/users says how it signs in to the UI:
    has_password, must_change (a password set for it, to be changed at
    the next sign-in) and last_sign_in_at. The schema is UserInfo, the
    fields of User and 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.

  • accounts on GET /v1/sends: the audit of the named accounts alone,
    as /v1/messages and /v1/changes take it. An account the caller
    may not audit is left out without a word.

  • GET /v1/status (get_status, in accounts.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 needs get_status too, which accounts.read holds.

Changed

  • Breaking: POST /v1/oauth/{provider}/start is gone, and with it
    the right start_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 naming start_oauth keeps its other
    rights.
  • Breaking: DELETE /v1/users/{user_id}/tokens/{token_id} answers
    204 without a body, as every other delete does. It answered 200
    with the token's record. The token stays in
    GET /v1/users/{user_id}/tokens with its revoked_at.
  • disabled is no longer a value of an account's status: nothing
    ever set it. The values are connected, needs_reauth and
    unreachable.
  • The OpenAPI document names on each operation the errors it can
    answer: 413, 429 and 500 on every one, 404 and 409 where a
    record is touched, 501 and 502 where 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
    answers 400 invalid cursor: start the list again.
  • What an account cannot do answers 501 not_supported with the same
    message for every kind of account, e.g. "this account keeps no
    drafts". A change of a POP3 message answers 501 even 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 with 500. Before, the
    change stood and the log said system.not_audited. A user's deletion
    now removes its tokens, password, webhooks and the user in one step as
    well.
  • backup writes format 2: the database is encrypted in blocks of 1 MiB
    from a copy beside the database, and restore and backup 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_ID stops 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.yaml hands the MCP server its
    API token as MAILBOX_SERVICE_TOKEN, the name the server reads. The
    variable MAILBOX_MCP_API_TOKEN is gone.
  • Breaking: containers/compose.yaml moved to containers/dev/ and
    builds from the repository only. MAILBOX_SERVICE_IMAGE and
    MAILBOX_MCP_IMAGE are gone: the published images run from
    containers/production/. The Dockerfiles are in containers/images/.
  • Breaking: a key file in the data folder is refused
    (MAILBOX_SERVICE_KEY_FILE below MAILBOX_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 that paths names.
  • Breaking: GET /v1/accounts and GET /v1/users are paged like
    the other lists. They answer {"items": [...], "next_cursor": ...}
    instead of an array and take limit (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: user on Sends and
    Audit, recipient on Sends. A kept link with who or to no 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-client and mailbox-mcp. The OpenAPI document's title is
    mailbox-service, the MCP server's mailbox-mcp. On PyPI and
    ghcr.io the names stay benethos-mailbox-service,
    benethos-mailbox-client and benethos-mailbox-mcp.
  • A right of the service or admin in a grant's allow answers 400,
    and a right on accounts in service as well. Stored rights move at the
    first start: what a grant named of the service goes to service, a
    grant with accounts.manage on every account gets accounts.connect.
    Nobody loses a right. The log names each user and role whose rights
    moved.
  • accounts.manage is about existing accounts alone: update_account,
    delete_account and verify_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_id is null for them. Their ids stay.
  • A change that would leave no enabled administrator who can sign in to
    the UI answers 409: disabling, deleting, taking admin or the UI
    sign-in away, directly or through a role. Where there is none to begin
    with, nothing is held back. users set-password on the host stays the
    way back.

Fixed

  • GET /v1/sends goes 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 naming list_sends alone got every
    account's audit. Grants with the group audit were not affected.
  • backup FILE --recovery-key is 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 answers 502 provider_unavailable, the code stands,
    and the next poll waits longer. A token endpoint that answers 5xx or
    temporarily_unavailable is 502 provider_unavailable everywhere,
    not 502 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 with 400. Before, it ended in 500.
  • 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,
    else 400. 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, with 400. A host that is neither a
    name nor an IP address, e.g. imap.example.org:993, is refused with
    400 before it is looked up. Before, it ended in 502.
  • The sync worker forgets a deleted account. It kept a note of each one
    for as long as the service ran.
  • openapi and keys generate take --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. Its record was 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 in 404, with the draft saved and nothing sent. They
    now go on with the new id. The MCP server's update_draft says so.