
mcp-server
io.github.trekmail/mcp-server
Business email hosting: manage custom domains, mailboxes, calendars, contacts, and Drive.
Documentation
TrekMail MCP Server
A Model Context Protocol (MCP) server that exposes the TrekMail API v1 as 285 agent tools. This is a thin adapter — all business logic lives in the TrekMail API; this server handles transport, authentication, retries, and safety gates.
Current release: package 1.18.0, catalogue 2026-11-15.1.
Connect in Claude
For the hosted service, open TrekMail in the Claude directory, select Connect, sign in to TrekMail and approve the requested permissions. TrekMail is published as a Community connector. Available tools depend on the connected account's plan and permissions.
For a White Label dashboard, add a custom connector using the MCP URL shown in that dashboard and your own brand name. The shared TrekMail listing signs in on TrekMail and does not replace your branded connection.
See the connection guide for other clients. The npm and Docker instructions below run the MCP adapter locally; the adapter still calls your configured TrekMail API.
Quickstart
npm
git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build
TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
npm start
Docker
git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .
docker run -i \
-e TREKMAIL_BASE_URL=https://trekmail.net \
-e TREKMAIL_API_TOKEN=tm_live_your_token \
trekmail-mcp
Dual-Token Architecture
The MCP server supports two independent token types. At least one is required:
| Token | Env Var | Prefix | Unlocks |
|---|---|---|---|
| Ops token | TREKMAIL_API_TOKEN | tm_live_ | 220 infrastructure tools (White Label branding, clients, team access, client storage limits and activity; domains; DNS; mailboxes; Drive; migrations; SMTP; tickets; account; billing; verifier; Cloudflare; and related administration) |
| Message token | TREKMAIL_MESSAGE_TOKEN | tm_msg_ | 65 message tools (messages, attachments, drafts, bulk actions, folders, scheduled send, contacts, contact groups, calendar, compose helpers, connected accounts, identities, templates, blocked senders) |
Tools are registered conditionally — only token types you provide get their tools. You can supply one or both:
# Infrastructure only
TREKMAIL_API_TOKEN=tm_live_your_token npm start
# Messages only
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token npm start
# Both
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
npm start
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
TREKMAIL_BASE_URL | Yes | — | Your TrekMail instance URL |
TREKMAIL_API_TOKEN | At least one token | — | Ops token (must start with tm_live_) |
TREKMAIL_MESSAGE_TOKEN | At least one token | — | Message token (must start with tm_msg_) |
TREKMAIL_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds |
TREKMAIL_USER_AGENT | No | trekmail-mcp/1.18.0 | User-Agent header |
TREKMAIL_ALLOW_DESTRUCTIVE | No | false | Enable high-impact changes (White Label access/branding, mailbox storage sizes and client storage limits, delete intents, domain deletion, forwarding, password changes, SMTP, credential revocation, Drive trash/purge, and message deletion) |
TREKMAIL_ALLOW_SENDING | No | false | Enable external sends, including send_message and White Label invitations |
TREKMAIL_ALLOW_MIGRATION | No | false | Enable migration write tools (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection) |
TREKMAIL_TOOLSETS | No | all | Comma-separated product sets to register, for example email or email,contacts,calendar |
TREKMAIL_SCOPE_AWARE_REGISTRATION | No | true | Discover the token's effective capabilities and domain/mailbox constraints at startup and omit unusable tool schemas; set false only as a compatibility escape hatch |
TREKMAIL_READ_ONLY | No | false | Register read tools only, even when the token can write |
Tool visibility is the intersection of token capability, TREKMAIL_TOOLSETS,
TREKMAIL_READ_ONLY, and transport support. A token limited to some domains
also does not get update_account, set_client_limit or remove_client_limit,
which the API refuses to it whatever its scopes; update_account and
drive_folder_stop_sharing are withheld from a token limited to some mailboxes
(no mailbox stops a folder share, as in webmail). Runtime API authorization remains
authoritative. Account Drive and Mailbox Drive deliberately share one drive
toolset; all White Label capabilities share white_label. The concrete resource,
membership, entitlement, and token constraints decide what a call can access:
a token limited to some mailboxes, for one, reaches Account Drive only through
the folders shared with all mailboxes, as those mailboxes do in webmail.
Shared mailbox member tools require the matching shared mailbox permission
from your dashboard role as well as the mailbox API permission. Roles with
Read access can list members; changing members requires permission to manage
shared mailboxes.
Compact email, contacts, calendar, and email-settings selections also include
the existing read-only list_mailboxes tool so an agent can discover the
required mailbox ID without loading the full administration toolset.
For a normal mailbox project, this is the compact configuration:
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_TOOLSETS=email \
TREKMAIL_SCOPE_AWARE_REGISTRATION=true \
npm start
Tools (285)
The full catalog is 285 tools over stdio. On the hosted HTTP transport
drive_file_uploadis intentionally not registered (itslocal_pathwould read files on our server — see the note insrc/tools/drive.ts), so the HTTP MCP exposes 284. Tools also split by token type: 65 need a message token (tm_msg_), the rest an ops token (tm_live_). These are full catalog totals. A directory profile or a restricted grant can expose a smaller set, including browser handoffs for sensitive setup.Safety gates apply to the whole list, not just the rows that say so. Read tools are always registered; every tool that creates, changes or deletes something needs
TREKMAIL_ALLOW_DESTRUCTIVE=true, the sending tools needTREKMAIL_ALLOW_SENDING, and the migration test tools needTREKMAIL_ALLOW_MIGRATION. Some entries below repeat their gate inline — the absence of that note does not mean a tool is ungated.
Domains (ops token)
- list_domains — List domains with optional status/search filters
- get_domain — Get details for a specific domain
- get_domain_connect_setup — Check one-time Cloudflare DNS setup eligibility and return a browser handoff URL only when available; otherwise return blockers. Read-only; no API token or DNS change
- get_domain_alias — Check a domain's saved receive-only alias connection and whether it is delivering now
- set_domain_alias — Route matching addresses on this domain to a primary domain (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - remove_domain_alias — Disconnect the domain alias after
confirm_remove: true(gated:TREKMAIL_ALLOW_DESTRUCTIVE) - create_domain — Add a new domain to the account.
mail_hosting: "external"registers it as a sending-only domain: no MX record is asked for, it holds no mailboxes, and it serves purely as a verified From address - delete_domain — Delete a domain (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - update_domain_catch_all — Configure or clear the catch-all address
- set_domain_mail_hosting — Choose whether TrekMail hosts the domain's incoming mail or only sends for it. Switching to
externalstops its mailboxes receiving, so it needsconfirm_mailboxes_stop_receiving: true - list_forwarding_addresses — List mailbox-less forwarding addresses on a domain, with recipients, the per-domain limit, and whether the plan currently delivers them. Pro includes 100/domain; Agency includes 300/domain
- get_forwarding_address_log — Recent deliveries for one address: sender, destination, and outcome (delivered / deferred / rejected / blocked as spam before forwarding). Pro retains 7 days; Agency retains 30
- create_forwarding_address — Create a forwarding address — no mailbox, no storage. Delivery requires Pro or Agency; Nano and Starter keep saved rules inactive until upgrade (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - update_forwarding_address — Replace recipients, or pause / resume an address (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - delete_forwarding_address — Delete a forwarding address (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - retry_domain_dkim — Retry DKIM key provisioning
- update_domain_note — Update the admin note on a domain
- get_domain_signature — Read per-domain email signature settings (mode, position, HTML)
- update_domain_signature — Set per-domain signature (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - bulk_add_domains — Add up to 20 domains in one call
DNS (ops token)
- get_dns_requirements — Get required DNS records for a domain
- dns_recheck — Trigger async DNS verification (returns check ID)
- get_dns_check — Poll DNS check status/results
White Label (ops token)
These 23 tools are omitted unless White Label entitlement and the token's live scopes allow them. During cancellation grace, only the owner keeps read tools; writes and delegated access are removed.
- get_domain_branding — Read a domain's brand, assets, hosts, mail zone, and required DNS records
- set_domain_branding — Partially update domain or account-default branding (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - set_domain_brand_logo — Upload a base64 PNG/JPEG/ICO brand asset (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - verify_domain_branding_dns — Queue DNS and certificate verification (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - create_branding_preview — Create a short-lived branded preview (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - remove_domain_brand_logo — Remove a brand asset (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - remove_domain_branding — Clear domain or account-wide branding (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - get_white_label — Read entitlement, setup progress, account brand, and reachable domain status
- get_white_label_access_catalog — Read roles, permissions, and domains this caller may grant
- list_white_label_members — Search or filter clients, members, and invitations
- get_white_label_member — Read one member, effective permissions, and allowed operations
- invite_white_label_member — Create and email an invitation (gated:
TREKMAIL_ALLOW_SENDING) - update_white_label_member — Change role, domains, permissions, or note (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - suspend_white_label_member — Stop access and revoke the member's keys (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - resume_white_label_member — Resume a suspended membership without restoring old keys (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - resend_white_label_invitation — Replace and email a pending invitation (gated:
TREKMAIL_ALLOW_SENDING) - remove_white_label_member — Remove access after explicit confirmation (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - restore_white_label_member — Restore membership without restoring old keys (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - list_white_label_activity — Read White Label account activity
- get_white_label_member_activity — Read one member's actions and sign-in history
- list_client_limits — List client storage limits: one budget in MB shared by the mailboxes and Drive in a client's domains, with what is reserved, shared and used, and the client's mailbox caps (
max_mailboxes,mailbox_size_mb) with themailboxesandpending_invitescounted against them - set_client_limit — Give a client's domains a storage limit, change it, or replace its domain set; optionally cap the client's number of mailboxes (
max_mailboxes, pending invitations included) and mailbox size (mailbox_size_mb: new mailboxes get it, none may be larger, no shared storage),nullremoves a cap; needs a token that reaches every domain (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - remove_client_limit — Remove a client storage limit after
confirm_remove: true; its domains go back to the account's storage and mailboxes keep their sizes (gated:TREKMAIL_ALLOW_DESTRUCTIVE)
Mailboxes (ops token)
- list_mailboxes — List mailboxes with optional domain/search filters
- get_mailbox — Get details for a specific mailbox, including
client_auth_mode(what mail apps may sign in with) where app passwords are available - get_mail_client_setup — Get password-free IMAP/SMTP settings, actual sending readiness, localized guides for five app families, and delegated shared-mailbox folders for a regular member mailbox;
authentication.password_sourceandaccepted_passwordssay whether the mail app takes the mailbox password or an app password - get_apple_mail_profile — Generate a password-free Apple Mail
.mobileconfigfile as Base64 (13 locales) - create_mailbox_generated_password — Create mailbox with auto-generated one-time password (optional
storage_allocation_mbcarves out dedicated storage from the account pool; omit for shared, or for the client'smailbox_size_mbwhere a client storage limit sets one). Optionalclient_auth_mode; on anapp_password_onlymailbox the generated password opens TrekMail webmail only, so mail apps (classic webmail included) need create_mailbox_app_password next - change_mailbox_password — Change the password for a mailbox; while app passwords are enabled, resetting the mailbox password automatically revokes all its app passwords (
mailbox_password_reset) (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - update_mailbox — Update a mailbox display name, a regular mailbox's webmail
conversation_viewpreference, or itsdrive_accesslevel (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - set_mailbox_storage — Move a mailbox between shared storage (
null) and a fixed size in MB, checked against the account pool and, in a domain under a client storage limit, that limit and itsmailbox_size_mb(no shared storage there) (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - set_mailboxes_drive_access — Set
drive_accesson many mailboxes at once, chosen by explicitmailbox_ids, bydomain_id, orall; shared mailboxes are skipped and counted (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - suspend_mailbox_login — Stop someone signing in to a mailbox while its mail keeps arriving: webmail/IMAP/SMTP and device passwords refused, open sessions ended, reset links dead, delivery untouched (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - resume_mailbox_login — Lift a sign-in suspension; device passwords revoked by it are not restored (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - set_mailboxes_login_access — Suspend or restore sign-in on many mailboxes, chosen by explicit
mailbox_ids, bydomain_id, orall; shared, paused and trashed mailboxes are skipped and counted (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - list_mailbox_app_passwords — List a mailbox's app passwords (name, created, last used, revoked) and its
client_auth_mode; secrets are never returned - create_mailbox_app_password — Create an app password for one mail app (IMAP, SMTP, ManageSieve, CalDAV/CardDAV): 16 letters returned once, up to 25 active per mailbox; never opens TrekMail webmail, though classic webmail takes it like any IMAP app (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - rotate_mailbox_app_password — Replace an app password with a new secret under the same name; the old one stops working at once (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - revoke_mailbox_app_password — Revoke an app password for good and sign out the app using it (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - set_mailbox_client_auth_mode — Set one mailbox (
mailbox_id) or a bulk selection (mailbox_ids,domain_idorall) toapp_password_only(mail apps, classic webmail included, need an app password; TrekMail webmail keeps the mailbox password) orpassword_or_app_password(gated:TREKMAIL_ALLOW_DESTRUCTIVE) - update_mailbox_note — Update the admin note on a mailbox
- pause_mailbox — Disable a mailbox entirely, delivery included — unlike
suspend_mailbox_login(gated:TREKMAIL_ALLOW_DESTRUCTIVE) - resume_mailbox — Re-enable a paused mailbox
- enable_imap — Enable IMAP access for a mailbox (required for Message API)
- bulk_create_mailboxes — Create 1-100 mailboxes at once with per-item
storage_allocation_mb, each checked as its row is created; a row that does not fit fails on its own (storage_pool_exceededorclient_storage_limit_exceeded), as does a row over the client's mailbox caps (client_mailbox_size_exceededorclient_mailbox_limit_reached)
Invites (ops token)
- create_invite — Send a setup invite to a recipient (optional
storage_allocation_mbpre-allocates dedicated storage; the recipient inherits it at redeem) - create_invites_bulk — Send up to 100 setup invites in one call (per-item
storage_allocation_mbsupported, each checked against what the earlier items left)
Aliases (ops token)
- list_aliases — List all aliases for a mailbox (includes primary address and plan limits)
- create_alias — Add an alias to a mailbox (cross-domain supported, Starter+ plans)
- update_alias — Toggle receiving, sending, or active/inactive status
- delete_alias — Permanently remove an alias (gated:
TREKMAIL_ALLOW_DESTRUCTIVE)
Shared Mailbox Members (ops token)
- list_shared_mailbox_members: List independent
can_read/can_sendpermissions andaccess(read_send, read_only, send_only); Read opens the shared inbox and, when enabled, a shared IMAP folder - add_shared_mailbox_member: Add an existing regular mailbox;
can_readandcan_senddefault to true (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - update_shared_mailbox_member: Change Read or Send as independently, or set the member's personal Webmail label; omitted fields keep their values; retryable native-sync failures preserve the old permission (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - remove_shared_mailbox_member: Revoke Webmail/native access without deleting the member mailbox; the last active reader cannot be removed (gated:
TREKMAIL_ALLOW_DESTRUCTIVE)
Shared mailboxes never authenticate directly. Call get_mail_client_setup with a regular member mailbox id, wait for native_access_ready=true and (for sending) send_as_ready=true, then inspect shared_mailboxes.items[] for exact Inbox/Sent/Archive/Junk paths and allowed operations. SMTP does not save a Sent copy; configure the client to append it to the returned shared Sent folder. Send-only addresses appear in delegated_send_addresses as {id, email, display_name} even when shared IMAP is disabled. Add each as an extra From address using the member’s own sign-in and app password; no shared folder is available, and sent mail belongs in their own Sent. The Message API excludes delegated identities and cannot send or schedule as a team address with send-only access yet. Permission changes may return no_access_left, send_only_disabled or last_reader (422).
Shared Mailbox Lifecycle (ops token)
- create_shared_mailbox — Create a shared mailbox with a required display name and one or more regular member mailbox ids (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - convert_mailbox_to_shared — Rotate a regular mailbox's credential, disable direct login, and assign members (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - convert_shared_mailbox_to_regular — Revoke every member's Webmail/native access and set a fresh direct-login password; a retryable native-sync failure leaves it shared (gated:
TREKMAIL_ALLOW_DESTRUCTIVE)
Forwarding (ops token)
- get_forwarding — Read the current forwarding config for a mailbox. Returns the
targetsarray (one or more destinations),keep_copy, anddestination_limit(the plan-tier cap so the agent can preflight anset_forwardingcall without trial-and-error). - set_forwarding — Configure one or more forwarding destinations for a mailbox, plus enable/disable and keep-copy. The
targetsarray accepts up to 30 entries client-side; the server enforces the actual per-plan cap — Starter 5, Pro 15, Agency 30 — and returns a 422limit_exceedederror with the cap if you pass more. CRLF / loop / self-forward / MX validation is run per destination, so a single bad entry rejects the whole save.
Mail Filters (ops token)
- list_mail_rules — List all mail filters for a mailbox
- get_mail_rule — Get a single mail filter by ID
- create_mail_rule — Create a new filter with conditions and actions
- update_mail_rule — Update an existing filter
- delete_mail_rule — Delete a filter (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - reorder_mail_rules — Change filter execution order
Auto-Reply (ops token)
- get_auto_reply — Get vacation auto-reply settings for a mailbox
- set_auto_reply — Configure auto-reply subject, message, dates, and list skipping
Sieve (ops token)
- get_sieve_script — Get the raw Sieve script for a mailbox
- upload_sieve_script — Upload a raw Sieve script for a mailbox
Delete Intents (ops token, two-step)
- create_delete_intent: Step 1, create a delete intent that expires in 10 minutes (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - confirm_delete_intent: Step 2, confirm it with
confirm: true; the mailbox moves to the recycle bin and can be restored within the retention window (default 7 days), after which it is purged for good (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - list_trashed_mailboxes: List the mailboxes in the recycle bin, optionally only on one
domain_id - restore_mailbox: Bring a mailbox back from the recycle bin; fails with
mailbox_limit_reachedwhen the domain is at its mailbox limit,client_mailbox_limit_reachedwhen the client already has itsmax_mailboxes, orstorage_pool_exceededwhen its fixed size no longer fits the account's free storage or, in a domain under a White Label client storage limit, what that limit has left (gated:TREKMAIL_ALLOW_DESTRUCTIVE)
Messages (message token)
Many message tools accept an optional
external_account_idto operate on a connected external mailbox (Gmail/Outlook/IMAP) instead of the primary mailbox. The id is always scoped to the token's mailbox (cross-mailbox access is impossible); discover valid ids withlist_external_accounts. Supported on:list_messages,read_message,send_message,move_message,update_message_flags,delete_message,list_folders,download_attachment,download_all_attachments,get_raw_message,save_draft,update_draft, andbulk_action(native actions only: read/unread/star/unstar/delete/move).report_spam/report_ham(andbulk_actionspam/notspam) train THIS server's spam filter, which doesn't apply to a remote provider, so they rejectexternal_account_id— move to the provider's Junk folder instead.
- list_messages — List messages in a mailbox folder with cursor pagination (optional
external_account_id);querytakes the webmail search operators,scopesearches subfolders or every folder (at most 20 newest matches, no pagination) - read_message — Get a single message by IMAP UID with full body (optional
external_account_id) - send_message: Send an email from the mailbox: or, with
external_account_id, from a connected account via its own SMTP, or, withshared_mailbox_id, as a shared team mailbox where the acting member has both Read and Send as (dual safety gates, validates total recipients ≤ 10, requires body). The mailbox's Default CC/BCC apply exactly as they do in the web app; passapply_default_recipients: falseto skip them for one message. Delegated team identities for send-only members are excluded; use webmail or a mail app for those addresses. Returns once the message is accepted, not sent: confirm withget_message_delivery. A used-up sending allowance fails at once withsending_limit_exceeded, naming the allowance and when it renews (resets_at); it is never worth retrying before then - get_message_delivery — What happened to a message
send_messageaccepted (pending, sending, sent, failed, delivery_uncertain), looked up by therequest_idit returned; a message refused by a sending allowance reports which one and when it renews. Works with any message token for the same mailbox, not only the one that sent the message, so a later hosted session or a renewed token can check an earlier send; an unknownrequest_idis a 404 - get_mailbox_sending_limits — How many more recipients this mailbox can send to today (
remaining_today), the most recipients one message may have, when the allowance renews, and the API's own caps for this token. While the lowest allowance is the account-wide total,limit_todayisnulland so isremaining_todayuntil that total is spent (then0); an ops token reads the total withget_sending_limits - delete_message — Permanently delete a message by IMAP UID (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - move_message — Move a message to a different IMAP folder
- list_folders — List all IMAP folders for the mailbox
- update_message_flags — Update flags (read/unread, starred/unstarred) on a message
- download_attachment — Download a single attachment by index from a message: base64 up to 25 MB; a bigger file, or
link_only: true, returns a short-liveddownload_url(any size, a plain HTTP GET with no auth header, beforeexpires_at) — since 1.16.0 - download_all_attachments — Download all attachments as a ZIP archive: base64 up to 25 MB; a bigger archive, or
link_only: true, returns a short-liveddownload_urlthe same way — since 1.16.0 - get_raw_message — Get the full RFC 822 raw source of a message
- save_draft — Save a new draft via IMAP APPEND; returns its
uidanduidvalidityfor later updates - update_draft — Replace a draft using its required
uidanduidvalidity; returns the replacement pair because the old UID stops working - report_spam — Report a message as spam (trains Rspamd Bayesian filter)
- report_ham — Mark a message as not spam (trains Rspamd Bayesian filter)
- bulk_action — Perform a bulk action on up to 50 messages (read, unread, star, unstar, delete, move, spam, notspam), or with
select: "matching"on every message aquerymatches in one folder (read, unread, star, unstar, move, delete;dry_runcounts first; at most 2,000 per call)
Connected accounts (message token)
Connect and manage external mailboxes (Gmail/Outlook/IMAP) the mailbox reads and sends through. Credentials are never returned by any tool.
- list_external_accounts — List connected external accounts (id, email, provider, status) — the source of valid
external_account_idvalues - detect_external_account — Detect provider preset (host/port/encryption, app-password vs OAuth) from an email address
- test_external_account — Test unsaved IMAP/SMTP credentials without persisting (requires
TREKMAIL_ALLOW_MIGRATION=true) - create_external_account — Connect an external account (test-gated; requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - update_external_account — Update a connected account's settings/credentials (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - test_saved_external_account — Re-test a saved account and lift its circuit breaker (requires
TREKMAIL_ALLOW_MIGRATION=true) - delete_external_account — Remove a connected account and its stored credentials (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true)
Folders (message token)
- create_folder — Create a new IMAP folder
- rename_folder — Rename an existing IMAP folder
- delete_folder — Delete a leaf IMAP folder and its messages; child folders must be deleted explicitly first (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - empty_folder — Empty all messages from a folder without deleting the folder
Scheduled Messages (message token)
- schedule_message — Schedule a message to be sent at a future time (optional IANA
timezoneresolves naïve datetimes; explicit ISO offset always wins). Default CC/BCC are applied and stored with the message, solist_scheduledshows what will actually go out;apply_default_recipients: falseopts out; passshared_mailbox_idto schedule as a shared team mailbox you may send as - list_scheduled — List pending scheduled messages
- reschedule_message — Re-time a pending scheduled message in place (no resend, lighter throttle than schedule + cancel)
- cancel_scheduled — Cancel a scheduled message before it sends
Contacts (message token)
- list_contacts — List contacts with optional search
- create_contact — Create a new contact
- update_contact — Update a contact's details
- delete_contact — Delete a contact (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - import_contacts — Import contacts from CSV or VCF data
- export_contacts — Export all contacts as VCF
Contact Groups (message token)
- list_contact_groups — List contact groups
- list_contact_group_members — List the contacts in a group (paginated)
- create_contact_group — Create a new contact group
- update_contact_group — Rename or update a contact group
- delete_contact_group — Delete a contact group (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - add_contact_group_members — Add contacts to a group
- remove_contact_group_members — Remove contacts from a group
Calendar (message token)
- list_calendar_events — List calendar events with optional date range filter
- create_calendar_event — Create a new calendar event
- update_calendar_event — Update an existing calendar event
- delete_calendar_event — Delete a calendar event (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - respond_to_invitation — Accept, tentatively accept or decline a meeting invitation in a message: the reply goes to the organizer and an accepted event is saved in the calendar (sends email: requires
TREKMAIL_ALLOW_SENDING=trueandconfirm_send: true)
Compose Helpers (message token)
- prepare_reply — Get pre-filled reply data (quoted body, headers) for a message
- prepare_reply_all — Get pre-filled reply-all data for a message
- prepare_forward — Get pre-filled forward data for a message
Identities (message token)
- list_identities — List source-specific From addresses, connected-inbox Send As identities, reply policy, eligible domains, and permitted profiles; pass
shared_mailbox_idfor the addresses of a shared mailbox you may send as - create_identity — Configure a managed From address, or create a Send As identity: pass
external_account_idwhen that address's mail is read through a connected inbox, omit it when the mail is forwarded into this TrekMail mailbox instead - update_identity — Update an identity's display name, signature, reply-to, default flag, or Send As route
- delete_identity — Delete a Send As identity (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true) - set_reply_from_policy — Reply from the recipient address when possible, or always start from the default (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true)
Templates (message token)
- list_templates — List message templates
- create_template — Create a new message template
- update_template — Update a message template
- delete_template — Delete a message template (requires
TREKMAIL_ALLOW_DESTRUCTIVE=true)
Blocked Senders (message token)
- list_blocked_senders — List blocked sender addresses
- block_sender — Block a sender address (moves future mail to Junk)
- unblock_sender — Unblock a sender address
SMTP (ops token)
- get_smtp_config — View current SMTP mode and connection details
- update_smtp_config — Update SMTP configuration (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - delete_smtp_connection — Delete a custom SMTP connection (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - test_smtp — Start an async SMTP connection test (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - get_smtp_test_status — Poll SMTP test results
The five tools above are the legacy account-level SMTP controls — deprecated for routing (kept for back-compat only). Use the per-domain SMTP routing + account-default tools below for outbound delivery configuration.
Domain SMTP Routing (ops token)
- get_domain_smtp — Get a domain's outbound route (mode + selected profile;
effective_smtp_moderesolvesinheritto the account default) - set_domain_smtp — Set a domain's route:
platform(managed) /profile(saved profile) /not_configured/inherit(follow the account default) (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - list_domain_smtp_profiles — List the account's reusable saved SMTP profiles plus per-profile usage counts
- get_domain_smtp_profile_usage — List the exact domains and Send As addresses using one profile; credentials are never returned
- create_domain_smtp_profile — Create a reusable SMTP profile and apply it to a domain — stores credentials (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - update_domain_smtp_profile — Update a saved profile (affects every domain using it) (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - delete_domain_smtp_profile — Delete a saved profile (domains using it are reassigned) (gated:
TREKMAIL_ALLOW_DESTRUCTIVE) - test_domain_smtp — Test a route, connects out (returns
job_id) (gated:TREKMAIL_ALLOW_DESTRUCTIVE) - get_domain_smtp_test_status — Poll a route test by
job_id - get_account_smtp_default — Get the account-wide default route new domains start on (
default_smtp_mode+effective_default_smtp_modeplan-baseline fallback) - set_account_smtp_default — Set the account-wide default (
platform/profile/not_configured); optionalapply_to_allswitches every existing domain now (gated:TREKMAIL_ALLOW_DESTRUCTIVE)
Tickets (ops token)
- list_tickets — List support tickets with optional status/category filters
- get_ticket — Get ticket details
- get_ticket_messages — Get all messages in a ticket conversation
- create_ticket — Create a new support ticket
- reply_to_ticket — Reply to an existing ticket
- close_ticket — Close a ticket
Account (ops token)
- whoami — Get current token info and permissions
- get_account — Get account details, plan, limits, usage, and
new_mailbox_client_auth_modewhen both app passwords and the platform default for new mailboxes are enabled - update_account — Set
new_mailbox_client_auth_modefor future mailboxes; existing mailboxes retain their mode. Owner-only; requiresmailboxes:write, both platform flags, andTREKMAIL_ALLOW_DESTRUCTIVE - get_sending_limits — Today's sending allowance for the whole account: plan numbers after trial or first-payment caps, domains still in their first-week warm-up (and when they step up), what the first payment would change, and today's usage including forwarded mail
- get_billing_status — Get billing and subscription info
- list_invoices — List invoice history
Agent Purchases (ops token)
For an agent buying without a human in the loop. These need the billing:autopay scope and TREKMAIL_ALLOW_DESTRUCTIVE. Each purchase takes two calls: without credential the answer is a 402 with the exact amount to authorise, then the same call with a credential minted for that amount.
- agent_buy_verifier_credits: Top up email verification credits with a shared payment token (
spt_...);quantitymust be a published tier - agent_subscribe_mail_plan: Start a
prooragencymail plan, monthly or yearly, with a Stripe PaymentMethod (pm_...) at full price; callagent_reissue_keyafterwards - agent_subscribe_drive_addon: Start a Drive storage add-on with a Stripe PaymentMethod; no mail plan needed, and
size_gbmust be a published step - agent_subscribe_white_label: Start a White Label subscription with a Stripe PaymentMethod; no mail plan needed
- agent_reissue_key: Exchange a key issued through agent signup for one scoped to the plan the account now holds; the new key is returned once and the old one is revoked at once
Message Token Management (ops token)
- create_message_token — Create a message API token for a mailbox (returns plaintext once)
- list_message_tokens — List all message tokens for a mailbox
- update_message_token — Narrow a message token in place: drop scopes, bring its expiry forward or rename it (never widens)
- revoke_message_token — Revoke a message token (gated:
TREKMAIL_ALLOW_DESTRUCTIVE)
Migrations (ops token)
- test_migration_connection — Validate IMAP credentials and discover source folders with message counts
- list_migrations — List migrations with optional status/mailbox filters
- get_migration — Get detailed migration status including per-folder progress
- start_migration — Start a new email migration (gated:
TREKMAIL_ALLOW_MIGRATION+confirm_start=true) - cancel_migration — Cancel a running migration (always available — safety operation, requires
confirm_cancel=true) - retry_migration — Retry a failed or cancelled migration (gated:
TREKMAIL_ALLOW_MIGRATION+confirm_retry=true) - delete_migration — Delete a migration record (gated:
TREKMAIL_ALLOW_MIGRATION+confirm_delete=true)
Bulk Migrations (ops token)
- preview_bulk_migration — Validate and preview a bulk migration batch (gated:
TREKMAIL_ALLOW_MIGRATION) - start_bulk_migration — Start a bulk migration batch (gated:
TREKMAIL_ALLOW_MIGRATION+confirm_start=true) - list_bulk_migrations — List bulk migration batches with optional status filter
- get_bulk_migration — Get details of a bulk migration batch
- cancel_bulk_migration — Cancel an active bulk batch (requires
confirm_cancel=true) - retry_bulk_migration — Retry failed jobs in a batch (gated:
TREKMAIL_ALLOW_MIGRATION+confirm_retry=true) - resume_bulk_migration — Resume a paused batch (requires
confirm_resume=true) - delete_bulk_migration — Delete a terminal bulk migration batch (gated:
TREKMAIL_ALLOW_MIGRATION+confirm_delete=true) - update_bulk_migration_job_password — Update source password for a failed job (gated:
TREKMAIL_ALLOW_MIGRATION)
Spam Metrics (ops token)
- get_spam_metrics — Get daily spam protection metrics for a domain
- get_spam_summary — Get aggregated spam protection summary for a domain
Deliverability and Bounces (ops token)
- get_domain_deliverability: Outbound rollup for a domain over the last 1 to 90 days (default 30): sent, delivered, soft and hard bounces, delivery and bounce rates, and a health status of good, warning or poor
- list_domain_bounces: Recent hard and soft bounces per recipient for mail sent from a domain, each with the SMTP status code and the receiving server's response; filter by
typeorrecipient - list_mailbox_bounces: The same per-recipient bounces, for mail sent from one mailbox
Email Verifier (ops token)
- verify_email — Verify a single email address
- verify_email_bulk — Submit a bulk verification job
- verify_job_status — Check job progress and results
- verify_job_download — Download job results as CSV
- verify_credits — Check remaining credit balance
- verify_list_jobs — List all verification jobs
- verify_cancel_job — Cancel a running job and refund unprocessed credits
- verify_delete_job — Permanently delete a job and all results (GDPR)
Cloudflare (ops token)
- validate_cloudflare_token — Validate a Cloudflare API token
- list_cloudflare_zones — List DNS zones accessible by a Cloudflare token
- connect_cloudflare_domains — Connect domains to a Cloudflare account (creates new domains if needed; creating one also needs
domains:create) - preview_cloudflare_dns — Preview DNS changes that would be applied via Cloudflare. Optional
included_records({ domain_id: [record_ids] }) previews only selected records - apply_cloudflare_dns — Apply DNS changes to Cloudflare-managed zones. Use
included_recordsto write only chosen records and skip the rest (e.g. MX now, DKIM later); omit it to apply all.confirmed_conflictsauthorises replacing records flagged as conflicting - list_cloudflare_tokens — List stored Cloudflare tokens
- delete_cloudflare_token — Delete a stored Cloudflare token (gated:
TREKMAIL_ALLOW_DESTRUCTIVE)
Idempotency
Mutating tools on idempotent API routes generate deterministic idempotency keys from sha256(tool_name + canonical_params). This covers POST, PUT, PATCH, and DELETE White Label operations. It means:
- The same tool call with the same params always produces the same key
- Agent retries hit the API's idempotency cache — no duplicate side effects
- You can override with an explicit
idempotency_keyparameter on any mutating tool
Drafts are the deliberate exception. save_draft and update_draft generate a fresh random
key per call, so two identical calls really do save two drafts, and updating a draft back to earlier
content really does perform the update instead of replaying an old response. Pass your own
idempotency_key on those two tools when you want retry-dedup.
A failed send is not replayed. Once a send_message delivery has failed (on a sending limit,
for example), the API no longer answers the same call with the earlier accepted response, so the
same message with the same content can be sent again later. A retry of a send that is still
pending or was delivered still gets the original response.
Safety
Two-Step Delete
Mailbox deletion requires two separate tool calls:
create_delete_intent→ returns intent with 10-minute expiryconfirm_delete_intent→ moves the mailbox to the recycle bin;restore_mailboxbrings it back within the retention window (default 7 days), after which it is purged for good
Destructive Operations Gate
Both delete tools require TREKMAIL_ALLOW_DESTRUCTIVE=true. Without it, they return an error message explaining how to enable.
The confirm_delete_intent tool has an additional confirm: true parameter that must be explicitly set.
Sending Safety Gates
The send_message tool has two independent safety gates that must both pass:
- Environment gate:
TREKMAIL_ALLOW_SENDING=truemust be set in the environment - Per-call gate:
confirm_send=truemust be passed as a parameter
This dual-gate design prevents accidental email sends. The agent must both be configured to allow sending and explicitly confirm each send.
Migration Safety Gates
The start_migration, retry_migration, and delete_migration tools require TREKMAIL_ALLOW_MIGRATION=true in the environment. cancel_migration is always available as a safety operation. test_migration_connection requires the gate because it makes outbound IMAP connections. Read-only tools (list_migrations, get_migration) work without any gate.
Additionally, each write tool requires a per-call confirmation parameter (confirm_start, confirm_cancel, or confirm_retry set to true).
Claude Desktop Configuration
{
"mcpServers": {
"trekmail": {
"command": "node",
"args": ["/path/to/trekmail-mcp/build/index.js"],
"env": {
"TREKMAIL_BASE_URL": "https://trekmail.net",
"TREKMAIL_API_TOKEN": "tm_live_your_token",
"TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
"TREKMAIL_ALLOW_SENDING": "true"
}
}
}
}
Claude Code Configuration
{
"mcpServers": {
"trekmail": {
"command": "node",
"args": ["/path/to/trekmail-mcp/build/index.js"],
"env": {
"TREKMAIL_BASE_URL": "https://trekmail.net",
"TREKMAIL_API_TOKEN": "tm_live_your_token",
"TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
"TREKMAIL_ALLOW_SENDING": "true"
}
}
}
}
Workflow Examples
DNS Recheck Loop
1. dns_recheck(domain_id: 5) → { check_id: 42 }
2. get_dns_check(check_id: 42) → { status: "pending" }
3. (wait) get_dns_check(check_id: 42) → { status: "complete", results: {...} }
Create Mailbox + Forwarding (single destination)
1. create_mailbox_generated_password(domain_id: 5, local_part: "alice")
→ { id: 10, email: "alice@example.com", password: "..." }
2. set_forwarding(mailbox_id: 10, enabled: true, targets: ["alice@gmail.com"], keep_copy: true)
Set Up a Mail App on a Mailbox That Takes App Passwords Only
# The generated password opens TrekMail webmail; Outlook, phones and calendars
# need an app password. Hand the secret to the user once and do not keep it.
# Ask for the mode explicitly: without client_auth_mode a new mailbox gets the
# platform default, password_or_app_password until the account-level default
# is switched on. The response's client_auth_mode is what was applied.
1. create_mailbox_generated_password(domain_id: 5, local_part: "dana", client_auth_mode: "app_password_only")
→ { id: 12, email: "dana@example.com", client_auth_mode: "app_password_only", one_time_password: "..." }
2. create_mailbox_app_password(mailbox_id: 12, name: "Outlook on work laptop")
→ { data: { id: 31, name: "Outlook on work laptop", password: "abcdefghijklmnop" }, message: "Shown once. ..." }
3. get_mail_client_setup(mailbox_id: 12)
→ { authentication: { username: "dana@example.com", password_source: "app_password",
accepted_passwords: ["app_password"], ... }, incoming: {...}, outgoing: {...} }
# Lost it later? rotate_mailbox_app_password(mailbox_id: 12, app_password_id: 31)
# returns a new secret and stops the old one at once.
Create Mailbox + Multi-Destination Forwarding
# Fan one shared mailbox out to several humans.
1. create_mailbox_generated_password(domain_id: 5, local_part: "sales")
→ { id: 14, email: "sales@example.com", password: "..." }
2. get_forwarding(mailbox_id: 14)
→ { enabled: false, targets: [], keep_copy: false, destination_limit: 15 } # Pro plan
3. set_forwarding(
mailbox_id: 14,
enabled: true,
targets: ["alice@example.com", "bob@example.com", "carol@example.com"],
keep_copy: true # also leave a copy in sales@ for record-keeping
)
Create Mailbox with Dedicated Storage
# Carve out 5 GB just for this mailbox — other shared mailboxes can't grow into it.
1. create_mailbox_generated_password(
domain_id: 5,
local_part: "ceo",
storage_allocation_mb: 5120
) → { id: 11, email: "ceo@example.com", password: "...", is_pooled_storage: false, storage_allocation_mb: 5120 }
Bulk Create with Mixed Storage Modes
# Mix shared and dedicated in one call. Each dedicated row is checked against
# the pool left when that row is created: rows that fit are created, and a row
# that no longer fits fails on its own with storage_pool_exceeded (207, or 422
# when every row fails).
1. bulk_create_mailboxes(items: [
{ domain_id: 5, local_part: "support" }, # shared
{ domain_id: 5, local_part: "founder", storage_allocation_mb: 10240 }, # 10 GB dedicated
{ domain_id: 5, local_part: "team-lead", storage_allocation_mb: 5120 }, # 5 GB dedicated
])
Cap a Client's Mailboxes
# Five mailboxes of 1 GB each for the client on domains 7 and 8, inside a 5 GB budget.
1. set_client_limit(domain_ids: [7, 8], storage_limit_mb: 5120, max_mailboxes: 5, mailbox_size_mb: 1024)
→ { id: 3, storage_limit_mb: 5120, max_mailboxes: 5, mailbox_size_mb: 1024, mailboxes: 0, pending_invites: 0, ... }
# New mailboxes and invitations there get 1024 MB when no size is given; a larger size fails with
# client_mailbox_size_exceeded, a sixth mailbox or invitation with client_mailbox_limit_reached.
# Existing mailboxes above a new cap keep working.
2. set_client_limit(client_limit_id: 3, max_mailboxes: null) # remove the maximum, keep the size
Invite Flow
1. create_invite(domain_id: 5, local_part: "bob", recipient_email: "bob@gmail.com")
→ { id: 1, status: "pending", invite_url: "..." }
Invite with Pre-Allocated Storage
# Pending dedicated invites count against the available pool until they
# are redeemed or expire — no over-committing.
1. create_invite(
domain_id: 5,
local_part: "exec",
recipient_email: "exec@external.com",
storage_allocation_mb: 10240
) → { id: 2, status: "pending", storage_allocation_mb: 10240 }
# When the recipient redeems, the new mailbox inherits the 10 GB dedicated allocation.
# If the pool no longer fits at redeem time, the new mailbox falls back to shared
# (the recipient sees a notice on the success page) — redeem itself never fails.
Safe Delete
1. create_delete_intent(mailbox_id: 10) → { id: 7, expires_at: "...", status: "pending" }
2. confirm_delete_intent(intent_id: 7, confirm: true) → { status: "confirmed" }
Monitor Inbox
1. list_messages(folder: "INBOX", limit: 10, unread_only: true)
→ { messages: [...], pagination: { has_more: true, next_before_uid: 45, next_before_date: 1760000000 } }
2. list_messages(folder: "INBOX", limit: 10, unread_only: true, before_uid: 45, before_date: 1760000000)
→ the next page: send both cursor halves (messages are ordered by date, not UID)
3. read_message(uid: 50) → { from, subject, body_text, body_html, attachments: [...] }
Email Migration
1. test_migration_connection(source_host: "imap.gmail.com", source_port: 993, source_security: "ssl", source_email: "user@gmail.com", source_password: "app-password")
→ { success: true, folders: { "INBOX": 1234, "Sent": 567, ... } }
2. start_migration(mailbox_id: 10, provider: "gmail", source_host: "imap.gmail.com", source_port: 993, source_security: "ssl", source_email: "user@gmail.com", source_password: "app-password", target_password: "mailbox-pass", confirm_start: true)
→ { id: 5, status: "pending", ... }
3. get_migration(id: 5) → { status: "processing", progress: 45, folders: [...] }
4. (poll) get_migration(id: 5) → { status: "completed", progress: 100, imported_messages: 1801 }
Send Email with Confirmation
1. send_message(
to: ["alice@example.com"],
subject: "Weekly Report",
body_text: "Please find the report attached.",
confirm_send: true,
idempotency_key: "weekly-report-2026-02-07"
) → { status: "queued", message_id: "uuid@trekmail.net", queued_at: "..." }
Drive Tools
42 tools for the /api/v1/drive/* REST surface (38 file/folder/share/addon
tools + 4 sync-device password tools added 2026-05-23). Drive is available
through both the TrekMail REST API and this MCP server when the ops token
has the matching Drive scopes. See the TrekMail app/API docs for the full
REST reference.
| Tool | Purpose |
|---|---|
drive_spaces_list | List Drive spaces this token can enumerate (account_drive + per-mailbox) |
drive_storage_summary | Account-wide pool snapshot (used / limit / addon flags) |
drive_space_usage | Per-space quota snapshot |
drive_browse_folder | Cursor-paginated listing of one folder's files + subfolders; with query, a name search across the whole space (3+ characters, up to 50 results per kind) |
drive_folder_tree | Flat tree of every folder in a space |
drive_select_all_ids | Bulk-select helper (capped at 5000 ids) |
drive_file_get | File metadata |
drive_file_download_url | Short-lived download URL (forced attachment) |
drive_file_rename / _move / _trash / _restore / _purge | File CRUD |
drive_folder_create / _update / _move / _trash / _restore / _purge | Folder CRUD; _update accepts name and/or color (#RRGGBB); _create accepts is_shared to publish to the whole account immediately |
drive_folder_share_with_account / _stop_sharing | Toggle whether a folder is visible to every mailbox in the account (Phase H — moves the folder + subtree from mailbox-personal Drive to account-drive when needed). A mailbox under a client storage limit cannot share out and does not see shared folders (shared_folder_client_storage_limit). Stopping a share needs a connection that is not restricted to mailboxes (shared_folder_stop_sharing_admin_only) |
drive_trash_list / _empty | Trash listing + nuke |
drive_bulk_trash / _restore / _move / _purge | One call, N items (cap 5000) |
drive_share_create / _list / _revoke | Public share-links (raw token returned ONCE) |
drive_file_upload | High-level: one tool, full flow. Streams local file → returned upload URL(s) → registers as available. Use this by default. |
drive_upload_initiate / _complete / _refresh_parts / _abort | Low-level multipart upload primitives — for agents that PUT bytes themselves |
drive_addon_get / _pricing / _cancellation_preview | Drive Storage Add-on (read-only; purchase / resize / cancel are dashboard-only by product decision) |
drive_device_list | List Drive sync-device passwords (label, scopes, mailbox binding, last-used, expiry, revoked-at; never plaintext) |
drive_device_create | Mint a new dsync_… credential for rclone / Cyberduck / X-Plore / DAVx⁵ / Documents / FolderSync. Plaintext returned ONCE in data.password. Rate-limited 20/h per account |
drive_device_revoke / drive_device_rotate | Revoke a device password (idempotent) or atomically rotate (revoke old + mint new, inherits label / scopes / mailbox). Both gated by TREKMAIL_ALLOW_DESTRUCTIVE=true. Rotate is rate-limited 10/h per account |
{space} parameters accept "account" (account-drive singleton),
"mailbox:N" (mailbox-personal), or a numeric DriveSpace.id.
Plan / addon gating
Drive scopes light up for any account on a paid plan OR with an
active Drive Storage Add-on (mirrors how verify:* works for the
Email Verifier). Free + addon active is a fully supported path —
mint a token with drive:account:read etc. and it works. When the
addon enters its 7-day post-cancellation grace window, write/share/
purge tokens lose access; read tokens keep working.
Drive API/MCP scopes:
| Scope | Enables |
|---|---|
drive:account:read | Browse Account Drive, inspect metadata, list folders/trash/share links, and request download URLs |
drive:account:write | Upload files, create/update/move/trash/restore files and folders in Account Drive |
drive:account:share | Create and revoke public share links for Account Drive files; with drive:account:write, share a folder with all mailboxes or stop sharing it |
drive:account:purge | Permanently purge trashed Account Drive files/folders and empty trash |
drive:mailbox:read | Browse mailbox Drive spaces allowed by token mailbox constraints |
drive:mailbox:write | Upload and mutate files/folders in allowed mailbox Drive spaces |
drive:mailbox:share | Create and revoke public share links for allowed mailbox Drive files |
drive:mailbox:purge | Permanently purge trashed files/folders in allowed mailbox Drive spaces |
drive:addon:read | Read Drive Storage Add-on status, pricing, and cancellation preview |
Upload flow
Default — drive_file_upload (one tool, all three steps):
drive_file_upload(space="account", local_path="/path/to/report.pdf",
folder_id=42, client_mime="application/pdf")
The wrapper:
- Reads file size and calls
drive_upload_initiate. - Streams the file straight to the returned upload URL(s). Bytes do NOT pass through MCP infrastructure beyond the wrapper process — and they never touch the API server. Memory stays bounded for files of any size (tested with multi-GB).
- For files ≥ 100 MB, uses multipart: 50 MB chunks, captures each upload part ETag, refreshes any expired part URL once before failing.
- Calls
drive_upload_completeto register the file as available. - On any error along the way, calls
drive_upload_abortto release the quota reservation. (The reservation is also reclaimed by the server-side cleanup — abort is a fast path, not a guarantee.)
Before anything is reserved, the wrapper checks the local file: a regular
file under $HOME or the temp directory (or under TREKMAIL_UPLOAD_DIR,
colon-separated), outside sensitive locations (~/.ssh, ~/.aws, /etc, …),
not named .env*, and with no second hard link. It opens the file once and
reads every byte from that handle, so replacing the path mid-upload changes
nothing.
Low-level primitives (drive_upload_initiate etc.) stay available
for agents that want to drive the PUT phase themselves — e.g. uploads
from a remote source instead of the MCP host's filesystem.
Audit attribution
Every mutating Drive tool stamps actor_type='api_token' and
api_token_id=<token id> on the audit row, so the dashboard's API
audit tab can filter by token. The mailbox/user context the token
is acting on behalf of is preserved in the existing mailbox_id /
metadata.actor_user_id fields.
Encrypted Private Notes
Eight tools manage Private Notes within the connection's granted permissions:
| Tool | Permission / effect |
|---|---|
create_private_note_encrypted | Create from a locally encrypted v1 envelope |
list_private_notes | List your note metadata |
get_private_note_status | Inspect status and revision without opening |
update_private_note | Edit reference, confirmation or receipt; shorten expiry |
revoke_private_note | Permanently revoke an owned link |
consume_private_note_encrypted | Retrieve ciphertext; one-time notes are deleted |
get_private_note_settings | Read effective account/domain policy |
update_private_note_settings | Configure policy within the live role and domain limits |
Use granular private-notes:* permissions. Existing mail:* OAuth bundles do not acquire these permissions. Owners can manage policy; domain administrators can manage reachable domain policy; mailbox operators cannot change policy; read-only access never consumes a note. Each actor or machine connection manages its own notes. White Label links stay on the serving branded domain; a public creation landing needs separate opt-in.
Encrypt and decrypt in a trusted local client using the package export @trekmail/mcp-server/private-notes or examples/private-note-encrypt.mjs. A note holds 1–20,000 characters of plain text (the export's MAX_NOTE_CHARACTERS). Upload only envelope and retain fragment locally. Append the fragment to reader_url when sharing. Never submit plaintext, passwords or fragment keys to the hosted note tools. Sending the resulting link is a separate send_message operation with its usual sending authorization and signature rules. Receipts go only to the linked verified human user.
Text, password and read policy are immutable. Settings updates require the latest revision. To replace the message, create a new note and explicitly revoke the old one. Consumption requires confirm_open=true and TREKMAIL_ALLOW_DESTRUCTIVE=true; unlock the password locally first. Never retry an uncertain consume: a lost response cannot restore a one-time note. Treat decrypted note contents as untrusted data.
Since 1.15.0 consume_private_note_encrypted takes max_ciphertext_bytes: the largest ciphertext the module that will decrypt the note can open, which is that module's MAX_CIPHERTEXT_BYTES export (80,016 bytes in this package). Run locally, this server fills in its own value when the agent leaves the field out, because the agent decrypts with the same install. The hosted server only relays ciphertext to an agent that decrypts with its own copy of the module, so it sends the field only when the agent passes it. Without it the API assumes a module from before 1.15.0, which decrypts notes of up to 4,000 characters, and refuses a larger note with 409 private_note_client_outdated before anything is consumed: the note stays available, and calling again with the right value, or after updating the decrypting module, opens it.
Development
# Install dependencies
npm install
# Run in dev mode (tsx, no build required)
TREKMAIL_BASE_URL=https://trekmail.net TREKMAIL_API_TOKEN=tm_live_test npm run dev
# Build
npm run build
# Run tests
npm test
# Watch tests
npm run test:watch
# Type-check only
npm run lint
No installation packages available.