Airpost
Contributing

Contributing

How to report issues, add a CLI command or MCP tool end to end, run the tests, and get a pull request merged into Airpost.

Bug reports, fixes, plugins and themes are welcome. The project is at github.com/airpost-mail/airpost. Read Architecture first if you’re changing anything below the UI; this page assumes you know where the engine, the protocol crate and the clients are.

Issues

File bugs and feature requests as GitHub issues. The issue forms ask for the version, platform, mail provider and relevant engine log lines (Developer > Open Engine Logs in the app, or airpost logs). Search existing issues first, closed ones included.

Report security problems privately, not in an issue. See Security.

Before you write code

For anything larger than a fix, open an issue first. New preferences for niche behaviour and changes to the plugin API need agreement before the code. A feature that can be a plugin or theme is often better as one.

Decide where the change belongs before you start:

The change is aboutIt goes in
What happens to mail, the database or the serverThe engine: apps/engine and the crates under it
A new thing clients can ask the engine forA method in crates/airpost-ipc, served in apps/engine/src
How a terminal user does somethingapps/cli
What an AI agent can doapps/mcp
Remote access, pairing, the web client’s serverapps/gateway
The desktop UIapps/desktop/src, src/features, or a plugin in apps/desktop/plugins
Multi-user features, sharing, trackingapps/backend

If the CLI or MCP server needs data the engine doesn’t expose yet, add the engine method first, in its own commit.

Set up

git clone https://github.com/airpost-mail/airpost.git
cd airpost
make setup
make mail        # fake IMAP and SMTP accounts, in another terminal
make desktop     # the desktop on .dev/profile with the debug engine

Add alice@airpost.test (password airpostpass) in the app. Its IMAP and SMTP servers are the ones make mail printed. Now make airpost ARGS="status" talks to the same engine. Full setup is in Building from source.

Walkthrough: add a CLI command

The CLI (apps/cli, binary airpost) is clap. It finds every running engine under the profile, says hello to each, and calls protocol methods. It never opens the database.

As an example, add airpost counts, which prints the unread and total counts of every folder and label from the engine’s counts.get method.

1. Declare the command

Subcommands are variants of Command in apps/cli/src/cli.rs. The doc comment is the help text.

// apps/cli/src/cli.rs, in `pub enum Command`
    /// Unread and total thread counts of every folder and label, by category id.
    Counts,

Global flags (--account/-a, --json, --config-dir) are already on Cli, so you don’t add them per command.

2. Dispatch it

apps/cli/src/app.rs connects to the engines with discovery::connect_all and matches on the command. Add an arm next to the read commands such as Command::Folders:

// apps/cli/src/app.rs, in the `match cli.command` after connect_all
        Command::Counts => crate::read::counts(&ctx, &mut engines),

3. Implement it

Put the function with the other read commands in apps/cli/src/read.rs. discovery::targets resolves --account (by id or email) to the engines that hold the accounts; app::call sends one request and maps a failure to a CliError that names the account and method.

// apps/cli/src/read.rs
use airpost_ipc::{method, CountsGetResult};

pub fn counts(ctx: &Ctx, engines: &mut [Engine]) -> Result<()> {
    let targets = discovery::targets(engines, ctx.account())?;
    let mut table = Table::new(vec!["ACCOUNT", "CATEGORY", "UNREAD", "TOTAL"], 1);
    let mut all = serde_json::Map::new();
    for t in &targets {
        let r: CountsGetResult = call(
            engines,
            t,
            method::COUNTS_GET,
            json!({ "accounts": [t.account_id] }),
        )?;
        for (id, c) in r.counts {
            all.insert(id.clone(), json!({ "unread": c.unread, "total": c.total }));
            table.row(
                vec![t.email.clone(), id, c.unread.to_string(), c.total.to_string()],
                c.unread > 0,
            );
        }
    }
    if ctx.json {
        output::json(&Value::Object(all));
    } else if table.is_empty() {
        output::line("No counts.");
    } else {
        table.print(&ctx.style);
    }
    Ok(())
}

Check the existing imports at the top of read.rs before adding these; most are already there. Follow the CLI’s conventions: --json prints one JSON document with every field, human output is a Table, and exit codes are 0 ok, 1 command failed, 2 usage, 3 no engine running.

4. Try it

cargo build -p airpost
make airpost ARGS="counts"
make airpost ARGS="counts --json"
make airpost ARGS="counts -a alice@airpost.test"

5. Test it

apps/cli/src/cli.rs has unit tests at the bottom that parse argument lists into Command values; add one for the new command. End-to-end CLI tests are Python in apps/engine/test/test_cli.py: they run a real engine on the fake IMAP server and call the airpost binary against its profile. Add assertions to test_cli_end_to_end, then run:

cargo test -p airpost
cargo build -p airpost-engine -p airpost
AIRPOST_ENGINE_BIN=target/debug/airpost-engine AIRPOST_BIN=target/debug/airpost \
  .venv/bin/python -m pytest apps/engine/test/test_cli.py -n 0

If the command is something an agent should know about, update skills/airpost/ too, and the CLI reference in these docs.

Walkthrough: add an MCP tool

The MCP server (apps/mcp, binary airpost-mcp) exposes tools over stdio and streamable HTTP. Every tool has a category (Read, Write or Send) that the access policy checks before the tool runs, and every lookup skips accounts and folders the policy hides.

As an example, add get_folder_counts, which returns the unread and total counts of one account’s folders.

1. Define the tool

Tool definitions are ToolDef values in the module for their kind: apps/mcp/src/tools/read.rs for reads, write.rs for changes, pim.rs for calendar and contacts, attachments.rs, followup.rs. Add one to read::definitions():

// apps/mcp/src/tools/read.rs, in definitions()
        ToolDef {
            name: "get_folder_counts",
            description: "Unread and total thread counts for each folder and label of an account, keyed by folder id (the ids list_folders returns).",
            schema: schema(
                json!({"accountId": {"type": "string", "description": "The account ID"}}),
                &["accountId"],
            ),
            category: Category::Read,
        },

definitions() in tools/mod.rs concatenates every module’s list in the order tools/list returns them. The description is what the model reads, so say what the result contains and which other tool produces the ids it takes.

2. Route the call

tools::call in apps/mcp/src/tools/mod.rs checks the policy for the tool’s category, then matches on the name. Add an arm:

        "get_folder_counts" => read::get_folder_counts(ctx, args),

3. Implement it

ctx.account resolves an id the policy allows, or fails as if the account didn’t exist. ctx.policy.folder_allowed filters out excluded folders. ctx.call sends one engine request.

// apps/mcp/src/tools/read.rs
pub(super) fn get_folder_counts(ctx: &mut Ctx<'_>, args: &Value) -> ToolResult {
    let account = ctx.account(&req_str(args, "accountId")?)?;
    let id = account.account_id.clone();
    let r = ctx.call(
        &id,
        airpost_ipc::method::COUNTS_GET,
        json!({ "accounts": [id] }),
    )?;
    let mut out = serde_json::Map::new();
    if let Some(counts) = r.get("counts").and_then(Value::as_object) {
        for (folder, c) in counts {
            if ctx.policy.folder_allowed(&id, folder) {
                out.insert(folder.clone(), c.clone());
            }
        }
    }
    Ok(Output::text(&Value::Object(out)).with_account(&id))
}

Output::text wraps the JSON in an MCP text block; with_account records the account for the audit log. Return ToolError::Denied for a policy refusal and failed(...) for anything else, so the audit log tells them apart.

4. Test it

Unit tests are in apps/mcp/src/tools/tests.rs, against a fake engine (tools/fake.rs) with helpers fake(), policy(level, accounts), run(...) and json_of(...). Test the happy path and the policy: a hidden account must read as unknown, an excluded folder must not appear.

#[test]
fn folder_counts_skip_excluded_folders() {
    let mut f = fake();
    let excl = policy(
        "read-only",
        json!({"a1": {"enabled": true, "excludedFolderIds": ["f-dr"]}}),
    );
    let counts = json_of(&run(&mut f, &excl, "get_folder_counts", json!({"accountId": "a1"})));
    assert!(counts.get("f-dr").is_none());
}

The fake answers the methods existing tools use; if it has no answer for counts.get, add one in tools/fake.rs. Then:

cargo test -p airpost-mcp

apps/engine/test also has end-to-end MCP tests run by make test. Document the tool in the MCP pages of these docs.

Running the tests

You changedRun
Rust (engine, CLI, MCP, crates)make test: cargo test --workspace, then the engine harness quick tier on the debug binaries
One cratecargo test -p <crate>
One harness scenarioAIRPOST_ENGINE_BIN=target/debug/airpost-engine .venv/bin/python -m pytest apps/engine/test -n 0 -k <name>
IMAP, DAV or server behaviour.venv/bin/python -m pytest apps/engine/test --all (both tiers, every server kind, needs Docker)
The schemacargo test -p airpost-store (the schema fixtures)
Protocol typesnpm run check in packages/client
Desktopmake test-desktop (or SPEC=<regex>), and npm run typecheck in apps/desktop
Web clientnpm test, npm run lint, npm run typecheck in apps/web
Anythingmake lint

make gate runs the full merge gate locally: fmt, clippy with -D warnings, cargo test --workspace --locked, cargo deny, release builds, and the harness quick tier on a serve engine with REQUIRE_AIRPOST=1.

Any log line the harness or a client matches on is a function in airpost_core::logmsg, and airpost-core/tests/logmsg.rs checks every function against the scenario regexes. If you change one of those lines, change the scenario in the same commit.

Debugging the engine

  • Logs. Each account logs to <profile>/engine-<accountId>.log, rotated at 5 MB to .log.1 through .log.3; lines without an account go to engine.log. airpost logs [ACCOUNT|engine|gateway|mcp-http] -f follows one. In the desktop, Developer > Open Engine Logs opens the folder.
  • Protocol traffic. engine.setLogLevel turns on verbose protocol logging (IMAP and SMTP lines, AUTH payloads never) for every account until a given time; running accounts restart to pick it up. The desktop’s Developer menu sends it.
  • Deltas. make airpost ARGS="watch" prints deltas as the engine sends them; --class Thread,Task narrows it.
  • Raw calls. make airpost ARGS="rpc <method> '<params-json>'" sends any method and prints the answer.
  • Tasks. make airpost ARGS="task list" shows queued and finished tasks with their errors.
  • stderr. The engine never writes stderr except for critical lines: the desktop treats stderr output as a crash. Don’t use println! or eprintln! in engine code; use tracing and airpost_core::critical!.
  • A debugger. Debug builds skip the program-name check, so you can run target/debug/airpost-engine --mode serve --detached --socket <path> under lldb or gdb with CONFIG_DIR_PATH pointing at a scratch profile and drive it with airpost --config-dir.

make build sets CARGO_PROFILE_DEV_DEBUG=0 to keep builds fast. For a debugger, build with CARGO_PROFILE_DEV_DEBUG=2 cargo build -p airpost-engine.

Pull requests

  • Contributions are accepted under the project’s licence, GPL-3.0-only. There is no CLA. See Licensing.
  • New dependencies must be GPL-3.0-compatible (MIT, Apache-2.0, ISC, BSD, MPL-2.0, Zlib, Unicode-3.0 for crates). Add Rust dependencies to [workspace.dependencies] in the root Cargo.toml and reference them with .workspace = true. CI checks crates with cargo deny and npm packages with .github/scripts/check-npm-licenses.mjs. Never enable a feature that pulls in OpenSSL or aws-lc-rs: TLS is rustls with ring.
  • Keep upstream copyright notices. Rust files start with // SPDX-License-Identifier: GPL-3.0-only and // Copyright (C) 2026 Airpost contributors; a file that ports C++ code opens with a module doc naming the C++ files and the upstream copyright.
  • Don’t add Mailspring branding or calls to *.getmailspring.com.
  • Changing a shared interface (ImapSession, Model, Store’s public methods, MetadataBackend, TaskRunnerFactory, WorkerContext) breaks other crates. Adding a method or field is fine; say so in the pull request when you change or remove one.
  • Keep a pull request to one change. CI runs the workflows for the paths it touches.

Commit messages

One line, area: what changed, describing the result rather than the work:

desktop: an installed on-demand service counts as running in Preferences
airpost-client: snap profile path uses the airpost snap name

The area is the app or crate (desktop, engine, airpost for the CLI, web, backend, gateway, airpost-mcp, or a crate name), or docs, ci, harness, packaging. Add a body when the reason isn’t obvious.

Code style

Prefer clear names and small functions over comments. A comment should say why the code is the way it is, or what a reader would otherwise get wrong, not restate the code or describe its history. Cite external evidence where it exists: an RFC section, an upstream commit, a provider quirk, a harness scenario name. apps/engine/CLAUDE.md and apps/desktop/CLAUDE.md in the repository describe each side’s conventions in detail, including the engine’s logging format and error types.

Code of Conduct

The project has a Code of Conduct. By participating you agree to abide by its terms.