io.github.trekmail/mcp-server
Business email hosting: manage custom domains, mailboxes, calendars, contacts, and Drive.
- Created
- 7 months ago
- Last commit
- 3 days ago
Security Findings
Tool name/behavior mismatch
MaliciousScanneragent_reissue_key: Handler overwrites the shared client's bearer token with the newly issued api_token from the response, silently switching credentials for every subsequent tool call in the server process.
Dangerous parameter surface
SuspiciousScanner1 tool(s) expose a command-execution parameter: upload_sieve_script.script
Recently created account
SuspiciousLineageAccount was 0d old when repo was created
Hardcoded secrets/API keys
SuspiciousScannerSecret Keyword: gener...****
No prior public repositories
SuspiciousLineageAccount has 1 public repos
Tools
278 tools exposed by this MCP server
agent_reissue_key
Exchange your key for one scoped to the plan the account now holds. Buying entitles the ACCOUNT, not the key that bought it, so without this you will keep getting 403 on domains and mailboxes after a successful purchase. Returns the new key ONCE and revokes the old one immediately. Only works for a key issued through agent signup — a connector authorised by a human must be re-authorised by that human instead.
upload_sieve_script
Upload and activate a custom Sieve script for a mailbox. This replaces any visual filters. The server validates syntax before activating. Agency plan only. Dangerous extensions (vnd.dovecot.pipe, vnd.dovecot.execute, vnd.dovecot.filter) are blocked.
add_contact_group_members
Add one or more contacts to a group.
add_shared_mailbox_member
Add a member to a shared (team) mailbox. Delegated dashboard roles need shared_mailboxes:write in addition to the mailboxes:write API grant; both mailboxes must be within the caller's domain and mailbox limits. Read (`can_read`) and Send as (`can_send`) both default to true. Set can_read=false and can_send=true for send-only access while the feature is enabled and another active reader remains. The API refuses no_access_left, send_only_disabled or last_reader with 422. Send-only members use webmail or a mail app; the Message API cannot send as their team address yet. For readers, use get_mail_client_setup with the member mailbox ID to wait for native_access_ready and verify effective send_as_ready plus exact folder paths.
agent_buy_verifier_credits
Top up email-verification credits by paying with a shared payment token. Call once without a credential to get a 402 with the exact amount, then again with a token minted for that amount. Quantity must be one of the published tiers. Credits work on every plan.
agent_subscribe_drive_addon
Start a Drive storage add-on subscription with a Stripe PaymentMethod. Sold on its own — no mail plan needed. Size must be one of the published steps; read /ai-agents/offer.json for the ladder and prices.
agent_subscribe_mail_plan
Start a mail-plan subscription using a Stripe PaymentMethod (NOT a shared payment token — those cannot back recurring billing). Only pro and agency can be bought this way: lower plans grant no permission to add domains or create mailboxes, so the purchase would be unusable. Full price, with no trial, discount or proration. After buying, call agent_reissue_key so your key matches the plan.
agent_subscribe_white_label
Start a White Label subscription with a Stripe PaymentMethod. Its own subscription; no mail plan required.
apply_cloudflare_dns
Apply DNS record changes via Cloudflare API. Creates MX, SPF, DKIM, DMARC records automatically. Use preview first to see what will change.
block_sender
Block an email address (e.g. spammer@evil.com) or entire domain (e.g. @evil.com). Max 50 per mailbox.
bulk_action
Perform an action on up to 50 messages at once, or on every message in the folder that a search matches. Actions: read, unread, star, unstar, delete, move, spam, notspam. The 'destination' parameter is required for 'move'. Or act on every match of a search in one folder: select='matching' with query instead of uids; dry_run=true first to count. Not spam/notspam; at most 2,000 per call (above that nothing changes, narrow by dates).
bulk_add_domains
Add multiple domains at once (up to 20). Returns per-domain results with success/error status.
bulk_create_mailboxes
Create multiple mailboxes at once (1-100). Each item specifies a domain and local part. password_mode='generated_one_time' lets the server generate one-time passwords (returned in each result row); 'user_supplied' requires items.*.password (default if omitted, for backward compat). Per-item storage_allocation_mb is optional — items without it use the shared account pool, or the client's mailbox size where one is set. Each dedicated allocation is checked as its row is created, against what the earlier rows left: a row that does not fit fails with storage_pool_exceeded, or with client_storage_limit_exceeded in a domain under a White Label client storage limit, and the other rows are still created. Returns per-item results with status codes (200 created, 207 partial success, 422 all failed). Pass create_app_password: true to also get each created mailbox's first app password in its result row (app_password, shown once).
cancel_bulk_migration
Cancel an active bulk migration batch. All queued and running jobs will be stopped. Set confirm_cancel=true to proceed.
cancel_migration
Cancel a running email migration. Set confirm_cancel=true to proceed.
cancel_scheduled
Cancel a pending scheduled message. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
change_mailbox_password
Change the password of a mailbox. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true because password changes are irreversible. While app passwords are enabled on the platform, this reset automatically revokes every app password of the mailbox (reason mailbox_password_reset), and the response includes app_passwords_revoked. Mail apps need new app passwords afterwards.
close_ticket
Close a support ticket. Cannot close an already-closed ticket.
confirm_delete_intent
Confirm a delete intent to delete a mailbox. This is step 2 of the two-step deletion process. The mailbox is moved to the recycle bin and can be restored within the retention window (default 7 days) with restore_mailbox; after that window it is permanently purged. Both TREKMAIL_ALLOW_DESTRUCTIVE=true and confirm=true are required.
connect_cloudflare_domains
Connect one or more domains to Cloudflare. Creates new TrekMail domains if they don't exist yet, and links them to Cloudflare zones for automatic DNS setup. Creating a domain (an entry without trekmail_domain_id) also needs the domains:create permission; linking existing domains needs only cloudflare:write.
convert_mailbox_to_shared
Convert an existing regular mailbox into a shared (team) mailbox. The specified members are added immediately. IMPORTANT: this rotates the mailbox password, revokes all of its app passwords and ends direct login for the original owner. The mailbox is then accessed through members' own accounts in Webmail and, when enabled, delegated native IMAP/SMTP folders. Use get_mail_client_setup with a member mailbox ID to discover the folder path.
convert_shared_mailbox_to_regular
Convert a shared (team) mailbox back to a regular user mailbox. ALL existing memberships, Webmail access, and delegated native IMAP access are revoked, then direct login is re-enabled with the supplied password. A retryable `native_access_sync_failed` leaves the mailbox shared. The password must be at least 12 characters and contain uppercase, lowercase, and at least one digit.
create_alias
Add a new email alias to a mailbox. The alias delivers mail into the same mailbox — no separate login needed. Optionally allow sending from this alias address. Requires Starter plan or above. Use list_domains to find domain IDs.
create_branding_preview
Mint a one-time preview link that shows the account dashboard under this domain's active White Label brand on a temporary preview host. The link signs the owner in once and expires quickly. Returns { url, expires_in }. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
create_calendar_event
Create a new calendar event.
create_contact
Create a new contact or return existing if email already exists.
create_contact_group
Create a new contact group (distribution list).
create_delete_intent
Create a delete intent for a mailbox. This is step 1 of the two-step deletion process. Returns an intent that expires in 10 minutes. The intent must be confirmed with confirm_delete_intent to proceed.
create_domain
Add a new domain to the account. The domain will start in pending_dns status. DNS records must be configured before it becomes active. Pass mail_hosting='external' when the customer keeps incoming mail at their current provider: no MX record is asked for, the domain hosts no mailboxes, and it is used only as a verified From address.
create_domain_smtp_profile
Create a reusable SMTP profile and apply it to this domain. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true (it stores credentials).
create_external_account
Connect an external account. Server-side test-gated: broken credentials never persist. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
create_folder
Create a new IMAP folder in the mailbox. Folder names cannot use reserved names (INBOX, Sent, Drafts, Junk, Trash, Archive, Scheduled). To create a nested subfolder, pass `parent` with the raw path of an existing folder (e.g. parent=
create_forwarding_address
Create a forwarding address on a domain: mail to it is handed straight on to the recipients, and the address itself stores nothing. No mailbox is created. Recipients can be addresses on other domains or mailboxes on this same domain, so a team address such as info@ can reach two people's mailboxes; any other address on this domain is refused. Delivery requires Pro or Agency; on Nano and Starter the rule is saved and starts working after an upgrade.
create_identity
Configure an existing mailbox/alias persona, or create a Send As identity. Pass external_account_id when you read that address's mail through a connected inbox; omit it when the mail is forwarded into this TrekMail mailbox instead. Either way, email must already be the mailbox address or a send-enabled alias. smtp_mode=domain follows Dashboard domain routing; smtp_mode=profile selects a saved profile and is limited to the account owner mailbox. Requires scope: messages:write.
create_invite
Create a setup invite for a mailbox. Sends an email to the recipient with a link to set their own password and complete mailbox setup. Storage defaults to the shared account pool, or the client's mailbox size where one is set; pass storage_allocation_mb to pre-allocate dedicated storage that the recipient inherits at redeem. In a domain under a White Label client storage limit (list_client_limits), that allocation must also fit in what the limit has left, or the call fails with client_storage_limit_exceeded.
create_invites_bulk
Create multiple setup invites in a single request. Each item specifies a local_part and recipient_email, and may optionally override the target domain via domain_id (otherwise the batch domain_id is used) — so one call can invite people onto several of your domains. Items without storage_allocation_mb use the shared account pool, or the client's mailbox size where one is set. A dedicated storage_allocation_mb is checked per item, against what the earlier items left: an item that does not fit fails with storage_pool_exceeded, or with client_storage_limit_exceeded in a domain under a White Label client storage limit, and the other items still go out. Returns results for each item.
create_mail_rule
Create a new mail filter for a mailbox. Filters automatically process incoming email based on conditions (sender, subject, body, size) and perform actions (move to folder, forward, flag, discard, reject). Pro and Agency plans only.
create_mailbox_app_password
Create an app password for one mail app or device on a mailbox: 16 lowercase letters, returned once under data.password (show it to the user in four groups of four, e.g. 'abcd efgh ijkl mnop'). It works for IMAP, SMTP (ports 465 and 587), ManageSieve and CalDAV/CardDAV, with the mailbox address as the username. It never opens TrekMail webmail, which takes the mailbox password; classic webmail (/webmail-old/) is a mail app here and accepts it.
create_mailbox_generated_password
Create a new mailbox with an auto-generated one-time password. The password is returned once and must be saved immediately — it cannot be retrieved later. Storage defaults to the shared account pool, or the client's mailbox size where one is set; pass storage_allocation_mb to carve out a dedicated allocation. In a domain under a White Label client storage limit (list_client_limits), that allocation must also fit in what the limit has left, or the call fails with client_storage_limit_exceeded. Where app passwords are available the response carries client_auth_mode, which is authoritative: the mode you pass, otherwise the platform default for new mailboxes (password_or_app_password until the account-level default is switched on). When it is 'app_password_only', the generated password signs in to TrekMail webmail only: mail apps (Outlook, Apple Mail, phones, IMAP/SMTP, calendars and contacts, and classic webmail at /webmail-old/) need an app password, so pass create_app_password: true to get the first app password in this same response, or call create_mailbox_app_password for each app the user sets up. To reset an existing mailbox password, use change_mailbox_password: while app passwords are enabled on the platform, that reset automatically revokes all its app passwords (reason mailbox_password_reset).
create_message_token
Create a message API token for a mailbox. The token grants access to read, write, or send messages for that mailbox. The plain token is returned only once.
create_shared_mailbox
Create a new shared (team) mailbox. The mailbox has no direct login; members use their own regular mailbox credentials in Webmail and, when enabled, delegated native IMAP/SMTP access. All members can read and can send as the shared address by default. Optionally use shared account storage or supply storage_mb for a dedicated allocation. In a domain under a White Label client storage limit (list_client_limits), that allocation must also fit in what the limit has left, or the call fails with client_storage_limit_exceeded.
create_template
Create a new email template.
create_ticket
Create a new support ticket. Requires a subject, category, and initial message.
delete_alias
Permanently remove an email alias from a mailbox. Mail sent to this address will no longer be delivered. This cannot be undone.
delete_bulk_migration
Delete a completed, failed, or cancelled bulk migration batch record. Cannot delete active batches. Both TREKMAIL_ALLOW_MIGRATION=true and confirm_delete=true are required.
delete_calendar_event
Delete a calendar event. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_cloudflare_token
Delete a saved Cloudflare token and disconnect all domains using it. Domains remain in TrekMail but lose their Cloudflare connection.
delete_contact
Delete a contact. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_contact_group
Delete a contact group. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_domain
Permanently delete a domain that has no active mailboxes left. While any mailbox remains, the call is refused with domain_has_mailboxes: delete the mailboxes first (they go to Recently deleted and no longer count). This action is irreversible. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_domain_smtp_profile
Delete a saved SMTP profile. Domains using it are reassigned automatically (to managed SMTP on paid plans, otherwise not_configured). Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_external_account
Disconnect (remove) an external account. Nothing is deleted on the provider side. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_folder
Delete a leaf IMAP folder and all messages it contains. A folder with child folders is rejected; delete its children explicitly first. Special folders cannot be deleted. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true. API: DELETE /api/v1/messages/folders/{path}. API documentation: https://trekmail.net/docs/ai-agents-api/api-overview
delete_forwarding_address
Delete a forwarding address. Mail sent to it bounces from then on — pause it instead to stop delivery temporarily.
delete_identity
Delete a Send As identity. Managed mailbox/alias and delegated team identities cannot be deleted here. Delegated identities are managed through shared-mailbox access (422 identity_delegated). Pass external_account_id for a connected-inbox identity. Requires scope: messages:write and TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_mail_rule
Delete a mail filter. This is irreversible. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_message
Permanently delete a message by IMAP UID. This marks the message as
delete_migration
Delete a completed, failed, or cancelled migration record. Cannot delete running migrations. Both TREKMAIL_ALLOW_MIGRATION=true and confirm_delete=true are required.
delete_smtp_connection
Delete a custom SMTP connection. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
delete_template
Delete an email template. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
detect_external_account
Given an email address, return the provider preset (IMAP/SMTP host/port, app-password requirement) for connecting it.
dns_recheck
Trigger an asynchronous DNS verification check for a domain. Returns a check ID that can be polled with get_dns_check.
download_all_attachments
Download all attachments from a message as one ZIP. Returns the ZIP base64-encoded when it is up to 25 MB. For a bigger one, or with link_only=true, returns instead a short-lived download_url (any total size; fetch it with a plain HTTP GET, no auth header, before expires_at) with size_bytes and count.
download_attachment
Download a single attachment from a message by its index. Returns base64-encoded content for files up to 25 MB. For a bigger file, or with link_only=true, returns instead a short-lived download_url (any size; fetch it with a plain HTTP GET, no auth header, before expires_at) with filename, content_type and size_bytes. Prefer link_only=true to save files without putting their bytes in the conversation.
drive_addon_cancellation_preview
What happens if the user cancels the add-on now: addon size vs plan quota, over-quota delta, sample of largest at-risk files, 7-day grace note. Read-only.
drive_addon_get
Current Drive Storage Add-on state: active flag, in_grace, size_gb, period end, hard-delete date if cancelled.
drive_addon_pricing
Pricing snap-points (250GB → 100TB) with monthly + yearly amounts in the requested currency. Default currency comes from the account's currency_preference.
drive_browse_folder
List folders + files in one Drive folder (or root when folder_id is omitted). Cursor-paginated with an opaque next_cursor; default per_page=50, max 200. If the response has has_more=true, request the next page with the returned next_cursor — do not crank per_page. To find an item by name anywhere in the space, pass query instead of walking folders (no paging; if meta.*_truncated, use a longer part of the name).
drive_bulk_move
Re-parent N items to target_folder_id (null = root). Files use a single UPDATE; folders go one-by-one for cycle detection.
drive_bulk_purge
DESTRUCTIVE. Hard-delete N TRASHED items. Items not currently in trash are silently skipped. Requires drive:*:purge scope AND TREKMAIL_ALLOW_DESTRUCTIVE=true.
drive_bulk_restore
Restore N trashed items in one call.
drive_bulk_trash
Soft-delete N items in one call. Caps at 5000 items per request.
drive_device_create
Mint a new Drive sync-device password for rclone, Cyberduck, DAVx⁵ and similar clients. The response includes data.server_url and returns the plaintext under data.password once; show both to the user and tell them to store the password now. Scopes must fit the account plan; mailbox scopes require mailbox_id. The account cap is 1000 stored device rows and creation is rate-limited to 20/hour.
drive_device_list
List active and revoked Drive sync-device passwords for the account. Each row includes the verified server_url to paste into a sync client, plus id, label, scopes, mailbox binding, timestamps, and active state. Never returns the plaintext password or its hash. Token mailbox_ids constraints are honored.
drive_device_revoke
Permanently revoke a Drive sync-device password. The sync client using it will lose access on its next request (no grace). Idempotent: revoking an already-revoked row is a no-op. Cannot be undone — to give the same client access again, create a fresh device password.
drive_device_rotate
Atomic credential rotation: revoke the old row and mint a new one inheriting label, scopes, and mailbox binding. The new plaintext password is returned in data.password (one-time). The old password stops working immediately. Optional expires_in_days overrides the inherited expiry — omit to keep the original window. Rate-limited 10/hour per account. Use this for scheduled credential rotation, NOT for changing scopes (revoke + create a new one for that).
drive_file_download_url
Returns a short-lived presigned URL (default ~5min) you can fetch directly to download the file bytes. URL forces attachment disposition. Does NOT stream bytes through MCP.
drive_file_get
File metadata: name, size, mime, status, scan status, has_active_share_link.
drive_file_move
Move a file to a different folder (folder_id=null moves to root).
drive_file_purge
DESTRUCTIVE. Permanently delete a TRASHED file. Bypasses the trash safety net. Requires drive:*:purge scope AND TREKMAIL_ALLOW_DESTRUCTIVE=true.
drive_file_rename
Rename a file. Validation: name passes the DriveItemName ruleset.
drive_file_restore
Un-trash a soft-deleted file. If parent folder is also trashed, file pops up at root.
drive_file_trash
Soft-delete: file moves to trash and active share-links are revoked.
drive_file_upload
Upload a local file to Drive in one tool call. Internally chains drive_upload_initiate → direct PUT(s) to B2 → drive_upload_complete. Bytes go straight to B2 — they do NOT pass through the API server (the server is only touched at the start and end of the upload). Files >100 MB use multipart (50 MB chunks); the wrapper streams from disk so memory stays bounded regardless of file size. On any error the wrapper calls drive_upload_abort to release the reservation.
drive_folder_create
Create a folder inside the space. parent_id=null creates at root. color is HEX (#RRGGBB); omitted = default slate gray. is_shared=true makes it visible to every mailbox in the account immediately (must be top-level — parent_id must be null when is_shared is true).
drive_folder_move
Re-parent a folder. parent_id=null moves to root. Cycle detection enforced server-side.
drive_folder_purge
DESTRUCTIVE. Hard-delete a TRASHED folder + its entire subtree. B2 cleanup runs async. Requires drive:*:purge scope AND TREKMAIL_ALLOW_DESTRUCTIVE=true.
drive_folder_restore
Restore a trashed folder + everything that was deleted in the same operation.
drive_folder_share_with_account
Make this folder visible to every mailbox in the account. If the folder lives in a mailbox-personal Drive, the entire subtree (folders + files) is migrated to account-drive in one transaction; quota counters move from mailbox to account. Restrictions: folder must be top-level (parent_id=null); subtree must contain ≤ 1000 files; account pool must have room for the migrated bytes. Needs drive:account:write and drive:account:share. Idempotent — calling on an already-shared folder returns it unchanged.
drive_folder_stop_sharing
Flip is_shared back to false on a shared folder. Folder stays in account-drive (no migration back to a specific mailbox); other mailboxes lose visibility, the dashboard owner keeps it as a private account-drive folder. Needs drive:account:write and drive:account:share and a connection not limited to some mailboxes (none stops a share, as in webmail). Idempotent on already-private folders.
drive_folder_trash
Soft-delete folder + entire subtree (cascade). Active share-links on contained files are revoked.
drive_folder_tree
Flat list of every folder in the space (id + name + parent_id + color). Useful for building a 'Move to' UI or computing paths client-side.
drive_folder_update
Update name and/or color. At least one must be set; both are optional independently.
drive_select_all_ids
Returns every file_id and folder_id directly inside the named folder (root when folder_id omitted). Capped at 5000 items — paginate via drive_browse_folder for larger folders.
drive_share_create
Mint a public share link for the file. Returns a raw token in the 'token' field — store it now, the API never returns it again. The 'public_url' field is the full /d/{token} URL ready to share.
drive_share_list
All share-links for a file (active + revoked). Raw tokens are NEVER included — use create's response to capture them.
drive_share_revoke
Revoke a share-link by id. Idempotent — second call no-ops.
drive_space_usage
Per-space quota snapshot. Same numbers as storage_summary but tagged to the resolved space.
drive_spaces_list
List Drive spaces this token can enumerate. Returns up to two kinds: "account_drive" (singleton, dashboard Drive) and "mailbox_personal" (one per mailbox). Token mailbox_ids constraint is honored. Empty data array means the token has no Drive scopes.
drive_storage_summary
Account-wide pool snapshot: used_bytes, limit_bytes, addon size, addon active/grace flags. Useful before initiating a large upload.
drive_trash_empty
DESTRUCTIVE. Permanently delete every trashed file + folder in the space. Requires drive:*:purge scope AND TREKMAIL_ALLOW_DESTRUCTIVE=true.
drive_trash_list
Soft-deleted files + folders in the space, newest-first. Cursor-paginated by deleted_at; default per_page=50.
drive_upload_abort
Cancel an in-flight upload, release the reserved quota, and clean up B2 multipart state.
drive_upload_complete
Finalise after the bytes are PUT to B2. Multipart calls must include parts:[{part_number,etag}] from each PUT response (etag stripped of B2's surrounding quotes). Single-PUT (small) calls send no parts.
drive_upload_initiate
Reserve quota and return presigned B2 PUT URLs. For files <100MB you get one URL; for larger files you get a multipart description (parts[]). The returned file row sits in pending_upload status until drive_upload_complete confirms B2 received the bytes.
drive_upload_refresh_parts
Re-presign expired part URLs for an in-flight multipart upload. Send the PartNumbers you still need.
empty_folder
Delete all messages in Trash or Junk folder. Only these two folders can be emptied. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
enable_imap
Enable IMAP access for a mailbox so message tokens can be created. Requires the current mailbox password.
export_contacts
Export all contacts as base64-encoded CSV or VCF.
get_account
Get account information including current plan, resource limits, feature flags, and usage counts. Includes new_mailbox_client_auth_mode only when app passwords and the platform default for new mailboxes are both enabled. Existing mailboxes keep their own mode; use update_account to change the default for future mailboxes.
get_account_smtp_default
Get the account-wide default outbound route that new domains start on (and that 'inherit' domains follow): default_smtp_mode (null until explicitly set) plus effective_default_smtp_mode, which is the plan baseline used when it's null (managed platform on paid plans, otherwise not_configured).
get_apple_mail_profile
Generate a password-free Apple Mail .mobileconfig file for a mailbox whose incoming and outgoing mail are ready. Returns file_name, media_type, encoding=base64, and content_base64. Decode the Base64 bytes to save or deliver the file; Apple prompts the user for the password during installation: the mailbox password, or an app password when the mailbox accepts app passwords only (see get_mail_client_setup authentication.password_source).
get_auto_reply
Get the vacation auto-reply settings for a mailbox. Shows whether auto-reply is enabled, the subject, message body, and date range.
get_billing_status
Get the current billing status including plan, subscription state, renewal/trial/cancellation dates, and provider.
get_bulk_migration
Get details of a bulk migration batch including per-job status breakdown.
get_dns_check
Get the status and results of a DNS verification check. Poll this after triggering dns_recheck.
get_dns_requirements
Get the DNS records that need to be configured for a domain. Returns SPF, DKIM and DMARC, plus MX when the domain's incoming mail is hosted here. A sending-only domain keeps its own provider's MX: that row appears under `checks` for reference and is never listed as required.
get_domain
Get detailed information about a specific domain, including its verification status and configuration.
get_domain_alias
Check whether a domain follows the addresses on a primary domain. The result clearly separates the saved connection from whether it is delivering right now, and never reveals a primary domain outside the token's domain access.
get_domain_branding
Read the per-domain White Label branding state: mode (off/inherit/custom), brand identity, mail-zone DNS/client-host status, verified DAV URL and certificate expiry, dashboard/webmail hosts, add-on state, and only the DNS records that still need attention. Create returned records with the Cloudflare DNS tools, then poll until client_hosts_status is 'active' and dav_ready is true.
get_domain_connect_setup
Check whether one-time Cloudflare Domain Connect is available for a TrekMail domain. If the domain and current grant allow it, return a TrekMail browser link for the customer to open and approve on Cloudflare. No Cloudflare API token is needed or saved; this read-only tool never starts consent or changes DNS. If unavailable, return the actual blockers instead of suggesting a nonworking link.
get_domain_deliverability
Get the outbound deliverability rollup for a domain — sent, delivered, soft/hard bounce counts, delivery rate, bounce rate, and health status (good/warning/poor). Mirrors the stats cards on the domain detail page.
get_domain_signature
Get the per-domain email signature settings (mode, position, html). Returns mode='off' when no signature is configured.
get_domain_smtp
Get the outbound SMTP route for a domain: mode (platform/profile/not_configured/inherit) and the selected profile. When mode=inherit, effective_smtp_mode shows what the account-wide default resolves to.
get_domain_smtp_profile_usage
Show every domain and Send As address currently using one saved SMTP profile. Use this before editing or deleting a shared profile. Requires scope: smtp:read.
get_domain_smtp_test_status
Poll the result of a domain SMTP test by job_id.
get_forwarding
Get the current forwarding configuration for a mailbox. Shows whether forwarding is enabled, the target addresses, and keep-copy setting.
get_forwarding_address_log
Recent deliveries for one forwarding address: when each message came in, who sent it, where it was forwarded, and the outcome — delivered, deferred, rejected by the recipient, or blocked as spam before forwarding. The window is the plan's retention (30 days on Agency, 7 otherwise); nothing older is kept.
get_mail_client_setup
Get password-free IMAP and SMTP settings plus localized three-step guides for Gmail, Outlook, Apple Mail, Thunderbird, and other IMAP apps. For each shared mailbox with Read, reports durable native-access readiness, effective send_as_ready/send_as_reason, exact Inbox/Sent/Archive/Junk paths, read/flag/folder/move/delete/send-as capabilities, and whether SMTP saves a Sent copy. Wait for native_access_ready=true and, for sending, send_as_ready=true. delegated_send_addresses lists send-only team addresses as {id, email, display_name}, even when shared IMAP is disabled. Add them as extra From addresses in the mail app using the member’s own sign-in and app password. They have no shared folders; save sent mail in the member’s own Sent. The Message API cannot use these delegated addresses yet. The user always authenticates with the regular member mailbox address; no password or custom SMTP provider credential is returned. authentication.password_source says which password the mail app takes: 'mailbox_password', or 'app_password' when the mailbox accepts app passwords only. Where app passwords are available, authentication also carries client_auth_mode, accepted_passwords (['mailbox_password', 'app_password'] or ['app_password']) and app_passwords_endpoint. When accepted_passwords lacks 'mailbox_password', create one with create_mailbox_app_password and give it to the user with these settings; the mailbox password will be refused by the mail app.
get_mail_rule
Get a single mail filter by ID.
get_mailbox
Get detailed information about a specific mailbox including its status, forwarding config, and domain. Where app passwords are available it also returns app_passwords_count (active visible app passwords, excluding platform system credentials) and client_auth_mode: 'app_password_only' means mail apps (IMAP, SMTP, ManageSieve, CalDAV/CardDAV) must sign in with an app password (see list_mailbox_app_passwords); 'password_or_app_password' means the mailbox password works in them too. TrekMail webmail always signs in with the mailbox password; classic webmail (/webmail-old/) is a mail app here, so on an app_password_only mailbox it takes an app password.
get_mailbox_sending_limits
How many more recipients this token's mailbox can send to today (remaining_today — the lowest of its own, its domain's and the account's allowance; null while that lowest is the account-wide total and some of it is left, which only an account token sees through get_sending_limits), the most recipients one message may have, when the allowance renews, and the REST API's own caps for this token. Recipients are counted across To, Cc and Bcc.
get_message_delivery
What happened to a message accepted by send_message: pending, sending, sent, failed or delivery_uncertain. Pass the request_id send_message returned; any message token for the same mailbox can check it. A message refused by a sending allowance has failure.code = sending_limit_exceeded with the allowance (dimension), its numbers and when it renews (resets_at).
get_migration
Get detailed status of a specific email migration, including per-folder progress breakdown and polling hint.
get_raw_message
Get the full RFC822 raw source of a message, including all headers. Useful for debugging delivery issues, analyzing headers, or forwarding as .eml. The API transports the source base64-encoded (raw_base64); this tool decodes it into a `raw` text field (non-UTF-8 bytes become replacement characters).
get_sending_limits
Today's sending allowance for the whole account, as the limit check sees it: the plan's numbers after trial or first-payment caps (`causes`), each domain still in its first-week warm-up with the dates its allowance steps up, what the first payment would change (`after_payment`), and today's account-wide usage including forwarded mail. Use it before a large send, or to explain a sending_limit_exceeded error. Allowances count recipients (To + Cc + Bcc) and renew at 00:00 UTC.
get_sieve_script
Get the current Sieve script for a mailbox. Returns the auto-generated script built from visual filters and auto-reply settings. Use this to inspect what is running on the server.
get_smtp_config
Get the current SMTP configuration for the account, including mode (platform/custom) and connection details.
get_smtp_test_status
Poll the result of an SMTP connection test by job_id.
get_spam_metrics
Get daily spam protection metrics for a domain. Shows inbound emails, spam caught, spam rejected, and clean emails per day.
get_spam_summary
Get a summary of spam protection for a domain. Includes total inbound, spam rate, protection status, and top triggered filter rules.
get_ticket
Get detailed information about a specific support ticket, including its status and metadata.
get_ticket_messages
Get all messages in a support ticket conversation, ordered chronologically.
get_white_label
See whether White Label is active or in read-only grace, the default brand, setup progress, and the status of every reachable branded domain.
get_white_label_access_catalog
List the roles, custom permissions, and domains this connection may grant. Read this before inviting or changing a team member.
get_white_label_member
Get one client or team member, including effective permissions, domain access, status, and the operations allowed in that state.
get_white_label_member_activity
Read one member's recent account actions and sign-ins, including time, approximate location, browser, operating system, and device type.
import_contacts
Import contacts from a base64-encoded CSV or VCF file (max 2 MB).
invite_white_label_member
Invite a client or teammate to the branded dashboard. Domain-scoped roles need at least one domain. A custom role needs permissions from get_white_label_access_catalog. Returns the delivery result and one-time invitation URL.
list_aliases
List all email aliases for a mailbox. Shows each alias address, receiving/sending status, and whether it's active. Also returns the primary address and usage limits (used/max).
list_blocked_senders
List all blocked email addresses and domains for the mailbox.
list_bulk_migrations
List bulk migration batches for your account. Supports filtering by status.
list_calendar_events
List calendar events within a date range with cursor pagination.
list_client_limits
List White Label client storage limits: each is one budget in MB for the mailboxes and Drive of a client's domains. Rows give id, storage_limit_mb, domain_ids, member_ids, allocated_mb (fixed mailbox sizes), pending_invites_mb (fixed sizes of open invites), pool_mb (left for shared storage) and used_bytes, with max_mailboxes, mailbox_size_mb (null = no cap), mailboxes and pending_invites (what counts against max_mailboxes). A connection limited to some domains sees only their limits.
list_cloudflare_tokens
List all saved Cloudflare API tokens for this account, with the number of connected domains for each.
list_cloudflare_zones
List all DNS zones accessible to a Cloudflare token, matched against your TrekMail domains. Shows which domains can be set up automatically.
list_contact_group_members
List the contacts that belong to a contact group, with pagination.
list_contact_groups
List all contact groups for the mailbox.
list_contacts
List contacts for the mailbox with optional search and pagination.
list_domain_bounces
List recent per-recipient hard/soft bounces for outbound mail sent from a domain. Each result includes the SMTP status code and the receiver's response, so you can diagnose exactly why specific messages failed (mailbox full, policy reject, bad recipient, etc.). RFC1918 IPs are masked in the response field.
list_domain_smtp_profiles
List the account's reusable saved SMTP profiles (with per-profile domain usage counts).
list_domains
List domains on the TrekMail account. Supports filtering by status and searching by name. Returns paginated results.
list_external_accounts
List the mailbox's connected external accounts (Gmail/Yahoo/iCloud/custom IMAP). Credentials are never returned.
list_folders
List all IMAP folders for the mailbox (or a connected external account). Returns each folder's name, raw path, delimiter, and hierarchy metadata (parent path, depth, has_children) so the folder tree can be reconstructed. Use the raw path with create_folder's `parent` to nest new folders.
list_forwarding_addresses
List mailbox-less forwarding addresses on a domain, with each address's recipients, whether it is paused, the per-domain limit, and whether the account's plan currently delivers them.
list_identities
List valid From addresses, connected-inbox Send As identities, reply policy, eligible domains, and permitted saved SMTP profiles. Pass external_account_id to see addresses usable from that connected inbox. Delegated team identities for send-only access are excluded and cannot be used for Message API sending or scheduling. Use webmail or a mail app for them. Requires scope: messages:read.
list_invoices
List billing invoices for the account. Returns invoice details including amounts, status, and download URLs.
list_mail_rules
List all mail filters for a mailbox. Filters automatically process incoming email — forward by sender/subject/content, sort into folders, flag, or discard. Pro and Agency plans only.
list_mailbox_app_passwords
List a mailbox's app passwords: the separate passwords mail apps (IMAP, SMTP, ManageSieve, CalDAV/CardDAV) sign in with. Returns client_auth_mode, the per-mailbox limit, active_count, and per row id, name, created_at, created_via, last_used_at, last_used_ip, last_used_protocol, revoked_at, revoked_reason and active. Secrets are never returned. client_auth_mode 'app_password_only' means mail apps must use an app password; 'password_or_app_password' means the mailbox password works in them too. TrekMail webmail always takes the mailbox password; classic webmail (/webmail-old/) is a mail app here, so on an app_password_only mailbox it takes an app password. A not_found error for a mailbox that exists means app passwords are not available on this platform yet.
list_mailbox_bounces
Same as list_domain_bounces but scoped to a single mailbox — useful for per-sender reputation triage. Returns per-recipient SMTP failures.
list_mailboxes
List mailboxes on the TrekMail account. Supports filtering by domain and searching by address. Returns paginated results. Where app passwords are available, each mailbox carries app_passwords_count (active visible app passwords, excluding platform system credentials) and client_auth_mode: 'app_password_only' (mail apps need an app password) or 'password_or_app_password' (the mailbox password works in mail apps too).
list_message_tokens
List all message API tokens for a mailbox. Shows token prefix, name, scopes, and status. Does not reveal the full token.
list_messages
List messages in an authorized mailbox IMAP folder, newest first (by date), with cursor-based pagination: while pagination.has_more is true, call again with before_uid = pagination.next_before_uid and before_date = pagination.next_before_date. A search page can come back short or empty while has_more is true — the search continues on the next page, so keep paging before concluding nothing matched. Filter with query (webmail operators). scope=subtree|all searches more folders: needs a filter, returns at most 20 newest matches with their folder, no paging. By default reads the TrekMail mailbox; external_account_id reads a previously connected external provider's IMAP inbox belonging to that mailbox. Requires messages:read scope; does not accept arbitrary server addresses or credentials.
list_migrations
List email migration jobs for your account. Supports filtering by status and mailbox.
list_scheduled
List scheduled messages for the mailbox with cursor pagination. Pass next_cursor from pagination to retrieve every result. By default only pending ones; status=limit_reached lists messages a sending limit held back when they came due — kept with their attachments and a `failure` (which allowance, when it renews) — which reschedule_message can send later and cancel_scheduled can delete.
list_shared_mailbox_members
List reachable members of a shared (team) mailbox within the caller's domain and mailbox limits. Delegated dashboard roles need shared_mailboxes:read in addition to the mailboxes:read API grant. Shows each member's membership id, the underlying user mailbox, email, and permissions: `can_read` (opens the shared inbox and, when enabled, a shared IMAP folder), `can_send` (Send as), and `access` (read_send, read_only or send_only). Send-only members send from their own webmail or mail app with no access to the team inbox. The Message API does not support delegated sending yet. In mail apps, members sign in with their own address and app password; no shared password exists. Use list_mailboxes to find mailbox IDs.
list_templates
List email templates for the mailbox.
list_tickets
List support tickets on the TrekMail account. Supports filtering by status and category. Returns paginated results.
list_trashed_mailboxes
List mailboxes currently in the recycle bin (soft-deleted, restorable). Each is permanently purged after its retention window elapses. Use restore_mailbox to recover one.
list_white_label_activity
Read the account's White Label access history: invitations, role and domain changes, suspensions, removals, restores, and related security actions.
list_white_label_members
List clients and team members with their roles, domain access, status, and allowed next actions. Owner rows are visible but cannot be changed here.
move_message
Move a message to a different IMAP folder. Copies the message to the destination and deletes it from the source.
pause_mailbox
Pause (disable) a mailbox. The mailbox will stop receiving and sending email until resumed.
prepare_forward
Get pre-populated forward data: subject (Fwd:), forwarded body, original attachment metadata.
prepare_reply
Get pre-populated reply data for a message: to, subject (Re:), quoted body, in_reply_to. Ready to pass to send or save_draft.
prepare_reply_all
Get pre-populated reply-all data: to + cc (all original recipients except self), subject (Re:), quoted body.
preview_bulk_migration
Validate and preview a bulk migration batch. Returns categorized results showing which rows are valid, invalid, or have warnings. Always run this before start_bulk_migration. Requires TREKMAIL_ALLOW_MIGRATION=true.
preview_cloudflare_dns
Preview what DNS records will be created, merged, or replaced for connected Cloudflare domains. Run this before apply to see what will change.
read_message
Read one message by IMAP UID, including full body and attachment metadata, from the authorized TrekMail mailbox or, with external_account_id, its previously connected external provider's IMAP inbox. Only sources belonging to the authorized mailbox are accessible. Requires messages:read scope; does not accept arbitrary server addresses or credentials.
remove_client_limit
Remove a client storage limit. Its domains go back to the account's storage; mailboxes keep their sizes and nothing is deleted. Needs a connection that reaches every domain of the account. Returns the domain_ids that went back.
remove_contact_group_members
Remove one or more contacts from a group.
remove_domain_alias
Stop this domain from using the same address names as its primary domain. Existing mailboxes, aliases and forwarding rules stay in place, but other unmatched addresses on this domain may stop receiving mail.
remove_domain_brand_logo
Remove a brand asset (slot=light/dark/favicon) from a domain's brand. The saved file is deleted. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
remove_domain_branding
Turn off White Label branding. scope=domain (default) turns it off for this domain only; scope=all turns it off for EVERY domain in the account — branded URLs stop serving. Saved brand assets are kept as drafts and can be re-enabled later. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
remove_shared_mailbox_member
Delegated dashboard roles need shared_mailboxes:write in addition to the mailboxes:write API grant; both mailboxes must be within the caller's domain and mailbox limits. Remove a member from a shared (team) mailbox, revoking Read and Send as access without deleting the member's own mailbox. The last active reader cannot be removed (422 last_reader when send-only members remain; last_member for the legacy case). A retryable `native_access_sync_failed` keeps the membership. Pass the membership row id from list_shared_mailbox_members.
remove_white_label_member
Remove a member and revoke the API and mailbox keys they created. The membership can be restored later, but old keys never return.
rename_folder
Rename an existing IMAP folder. Special folders (INBOX, Sent, Drafts, Junk, Trash, Archive, Scheduled) cannot be renamed. API: PATCH /api/v1/messages/folders/{path}. API documentation: https://trekmail.net/docs/ai-agents-api/api-overview
reorder_mail_rules
Change the execution order of mail filters. Filters are checked in order — first match wins.
reply_to_ticket
Reply to an existing support ticket. Cannot reply to closed tickets.
report_ham
Report a message as not spam (ham). Trains the anti-spam filter (Rspamd) and moves the message to INBOX. Returns whether Rspamd training succeeded.
report_spam
Report a message as spam. Trains the anti-spam filter (Rspamd) and moves the message to the Junk folder. Returns whether Rspamd training succeeded.
reschedule_message
Change the delivery time of a pending scheduled message without re-sending. Use this instead of cancel + schedule when the user only wants to move the send time — it does not consume a messages:send rate-limit slot. Also sends a message a sending limit held back (list_scheduled status=limit_reached): give it a time after the allowance renews.
resend_white_label_invitation
Replace a pending member's old invitation with a new one, email it, and return the new one-time URL. Only pending invitations can be resent.
respond_to_invitation
Accept, tentatively accept or decline a meeting invitation in the mailbox. The reply is a real email to the organizer from the invited address; on accept the event is saved in the calendar. Get uid, folder and the invitation attachment's index (ics_event with method REQUEST) from read_message. Needs confirm_send=true; counts against sending limits.
restore_mailbox
Restore a mailbox from the recycle bin back to active. Use list_trashed_mailboxes to find trashed mailbox IDs. Fails (422) with mailbox_limit_reached if the domain is now at its mailbox limit, with client_mailbox_limit_reached if the client already has its max_mailboxes (pending invitations count), or with storage_pool_exceeded if the mailbox's fixed size no longer fits in the account's free storage or, in a domain under a White Label client storage limit, in what that limit has left.
restore_white_label_member
Restore a removed membership. Accepted members return active; unaccepted invitations return pending. Old credentials remain revoked.
resume_bulk_migration
Resume a paused bulk migration batch (e.g., paused due to storage limits). Set confirm_resume=true to proceed.
resume_mailbox
Resume a paused (disabled) mailbox. The mailbox will start receiving and sending email again.
resume_mailbox_login
Lift a sign-in suspension so the user can sign in again. App passwords and Drive device passwords that the suspension revoked are not restored: every mail app needs a new app password (create_mailbox_app_password, or the user makes one in webmail under Settings > App passwords), and Drive sync needs a new device password.
resume_white_label_member
Restore a suspended membership. Previously revoked API and mailbox keys stay revoked.
retry_bulk_migration
Retry all failed jobs in a bulk migration batch. Requires TREKMAIL_ALLOW_MIGRATION=true and confirm_retry=true.
retry_domain_dkim
Restart DKIM key provisioning for a domain. Use this if DKIM provisioning failed or needs to be regenerated.
retry_migration
Retry a failed or cancelled email migration. Set confirm_retry=true to proceed.
revoke_mailbox_app_password
Revoke an app password for good. The mail app using it is signed out and cannot sign in again with it; the row stays in the list as revoked. Cannot be undone: to let the same app back in, create a new app password. Fails with conflict if it was already revoked.
revoke_message_token
Revoke a message API token. The token will no longer be usable for message operations. This action cannot be undone.
rotate_mailbox_app_password
Replace an app password with a new secret under the same name. The old secret stops working at once and the mail apps using it are signed out until the user enters the new one. Returns the new row (new data.id) with data.password once, plus replaced_id.
save_draft
Save a new draft to the IMAP Drafts folder. Accepts structured JSON with to, cc, bcc, subject, body (text/html), and optional base64 attachments. Returns the new draft's uid and uidvalidity; keep both together for update_draft.
schedule_message
Schedule an email to be sent at a future date/time. Requires TREKMAIL_ALLOW_SENDING=true and confirm_send=true.
send_message
Send an email from the mailbox. Requires a message token with messages:send scope. Both TREKMAIL_ALLOW_SENDING=true and confirm_send=true are required as safety gates. The message is queued for delivery and a message_id and request_id are returned immediately — accepted, not yet sent: sending allowances are checked again when it leaves the queue, so call get_message_delivery with the request_id to confirm it went out. If an allowance is already used up the call fails with sending_limit_exceeded, naming the allowance and when it renews; do not retry before resets_at. A message whose delivery failed can be sent again later with the same content: it is not answered with the earlier result.
set_account_smtp_default
Set the account-wide default route that new domains start on: 'platform' (managed, paid plans), 'profile' (a saved SMTP profile — pass smtp_connection_id), or 'not_configured'. Pass apply_to_all=true to also switch every existing domain to this route now. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
set_auto_reply
Configure the vacation auto-reply for a mailbox. Set a custom subject, message body, optional date range, and whether to skip mailing lists. Each sender receives the reply at most once every 7 days. Requires API write access available on Pro and Agency plans. API: PUT /api/v1/mailboxes/{id}/auto-reply. API documentation: https://trekmail.net/docs/ai-agents-api/api-overview
set_client_limit
Give a client's domains one storage budget for their mailboxes and Drive, or change it. Read list_client_limits first. Without client_limit_id, pass domain_ids and storage_limit_mb: domains without a limit get a new one, or join and change the one limit the other given domains share; domains under two limits are refused. With client_limit_id, change any of its storage_limit_mb, its domain_ids (the full new set; domains left out go back to the account's storage), max_mailboxes and mailbox_size_mb. A limit cannot go below what its domains reserve or store. Optionally cap the client's number of mailboxes (max_mailboxes) and mailbox size (mailbox_size_mb); existing mailboxes keep working when they are above a new cap. Needs a connection that reaches every domain. Returns the limit.
set_domain_alias
Make addresses on this domain receive mail at the same local part on a primary domain. For example, hello@brand.example follows hello@company.example. This is receive-only and does not add a sending address.
set_domain_brand_logo
Upload a brand asset for a domain, base64-encoded. slot=light is the logo for light backgrounds, slot=dark for dark backgrounds, slot=favicon is the browser-tab icon. content_base64 is the raw image bytes base64-encoded — PNG or JPG (favicon also accepts ICO), max 1 MB; SVG is not supported. Configure branding (set_domain_branding) before uploading. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
set_domain_branding
Configure White Label branding for a domain. PARTIAL update — only the fields you pass change; omit a field to leave it unchanged. mode=custom uses a domain-specific brand, mode=inherit uses the account default, mode=off disables branding. Set dashboard_enabled/webmail_enabled to claim branded URLs, and mail_zone_enabled to brand the DNS zone plus IMAP/SMTP client hostnames. This tool is available only while White Label is active. scope=domain (default) saves for this domain only; scope=account_default also makes it the account default for new domains; scope=all rolls this pattern out to every existing domain. After saving, call get_domain_branding to inspect DNS and provisioning state. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
set_domain_mail_hosting
Choose whether TrekMail hosts this domain's incoming mail or the customer keeps it with their current provider. 'external' asks for no MX record, allows no mailboxes, catch-all or forwarding on the domain, and uses it only as a verified From address — the forwarded-copy workflow. Switching an existing domain to 'external' stops its mailboxes receiving; nothing is deleted and switching back restores delivery.
set_domain_smtp
Set how a domain sends outbound mail: 'platform' (managed, paid plans), 'profile' (a saved SMTP profile — pass smtp_connection_id), 'not_configured' (block sending), or 'inherit' (follow the account-wide default). Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
set_forwarding
Configure email forwarding for a mailbox. Set targets, enable/disable forwarding, and choose whether to keep a copy in the original mailbox.
set_mailbox_client_auth_mode
Choose what mail apps (IMAP, SMTP, ManageSieve, CalDAV/CardDAV) may sign in to a mailbox with. 'app_password_only': only app passwords work in mail apps; open mail-app sessions are signed out (apps using an app password reconnect on their own) and an app that tries the mailbox password gets 'Sign-in failed. This mailbox accepts app passwords only'. 'password_or_app_password': the mailbox password works in mail apps again, next to app passwords. TrekMail webmail always signs in with the mailbox password (plus two-factor when it is on) in both modes; classic webmail (/webmail-old/) is a mail app here, so on an app_password_only mailbox it needs an app password too. Before tightening, create an app password for each device the user still syncs (create_mailbox_app_password), or those devices stop. Refused for shared mailboxes, and platform system mailboxes cannot be made app_password_only. Setting the current mode again changes nothing. Choose exactly ONE of mailbox_id, mailbox_ids, domain_id or all. Bulk selection is limited to 1000 matched mailboxes and narrowed to the token's allowed domains/mailboxes. Shared, trashed or deleting mailboxes, and system mailboxes when tightening, are skipped and counted; paused or sign-in-suspended mailboxes are updated. The bulk response has data.client_auth_mode, matched, updated and skipped. Returns 404 while app passwords are disabled; member tokens also need mailboxes:password:set.
set_mailbox_storage
Set an active or paused mailbox's storage to a fixed size in MB or to shared storage (null), with the dashboard's Edit storage checks. A fixed size must fit in the account's free storage, its current fixed size counting as free; in a domain under a client storage limit, also in what the limit has left, and never below what the mailbox already stores. Where the client has a mailbox size, a fixed size is at most that size unless it makes a larger mailbox smaller (client_mailbox_size_exceeded), and null (shared storage) is refused (client_mailbox_size_required); elsewhere shared storage is never refused for its size. Returns the updated mailbox.
set_mailboxes_drive_access
Set the Drive access level on many mailboxes at once. Choose the mailboxes with exactly ONE of: mailbox_ids (an explicit list), domain_id (every mailbox on that domain — the usual choice for a reseller applying a rule to one client), or all (every mailbox on the account). Shared mailboxes in the selection are skipped, since they have no Drive of their own. Nothing is deleted: files already stored stay until they are removed. Returns how many mailboxes matched, how many changed, and how many were skipped; mailboxes already on the requested level count as matched but not updated, so the call is safe to repeat.
set_mailboxes_login_access
Suspend or restore sign-in across many mailboxes; delivery is unaffected either way. Choose exactly ONE of: mailbox_ids, domain_id (every mailbox on that domain — the usual choice for one client), or all. Shared, paused and trashed mailboxes are skipped and counted. Mailboxes already in the requested state count as matched but not updated, so the call is safe to repeat. Suspending revokes each mailbox's app passwords and Drive device passwords; restoring does not bring them back, so mail apps need new app passwords afterwards.
set_reply_from_policy
Choose whether replies use the address that received the message or always use the mailbox default. Requires scope: messages:write.
start_bulk_migration
Start a bulk migration batch. IMPORTANT: Run preview_bulk_migration first to validate your data. Creates one migration job per valid row. Requires TREKMAIL_ALLOW_MIGRATION=true and confirm_start=true.
start_migration
Start migrating emails from a source IMAP server to a TrekMail mailbox. This is a long-running operation. Both TREKMAIL_ALLOW_MIGRATION=true and confirm_start=true are required.
suspend_mailbox_login
Stop someone signing in while their mail keeps arriving: webmail, IMAP, SMTP, app passwords, Drive device passwords and reset links are all refused and open sessions end, but delivery is untouched and nothing bounces. Every app password and Drive device password of the mailbox is revoked, not just paused. Use for a client who has not paid; pause_mailbox is harsher and stops delivery too. Shared mailboxes are refused — suspend their members instead. Lift with resume_mailbox_login.
suspend_white_label_member
Temporarily stop a member's access and revoke the API and mailbox keys they created. Read the member first to confirm suspend is allowed.
test_domain_smtp
Test a domain's SMTP route. mode='platform' tests managed SMTP via a domain mailbox; mode='custom' tests a saved profile (smtp_connection_id) or ad-hoc credentials. Returns a job_id to poll. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true (triggers outbound connections).
test_external_account
Test IMAP+SMTP credentials without saving. Makes an outbound connection. Requires TREKMAIL_ALLOW_MIGRATION=true.
test_migration_connection
Test IMAP connection credentials for email migration. Returns folder list with message counts if successful. Requires TREKMAIL_ALLOW_MIGRATION=true.
test_saved_external_account
Re-test a saved connected account's stored credentials. Makes an outbound connection. Requires TREKMAIL_ALLOW_MIGRATION=true.
test_smtp
Test an SMTP connection with the provided credentials. Returns a job_id to poll for results.
trekmail_internal_tool_list_initializer
Internal MCP capability initializer.
unblock_sender
Remove a sender from the blocked list. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
update_account
Set new_mailbox_client_auth_mode for mailboxes created from now on; existing mailboxes keep their own setting. 'app_password_only' requires app passwords in mail apps; 'password_or_app_password' also accepts the mailbox password. Requires mailboxes:write and the account owner's token or connector, not limited to some domains or mailboxes; every account member is refused with scope_blocked_by_membership. Returns 404 unless app passwords and the platform default for new mailboxes are both enabled. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
update_alias
Update an alias — toggle receiving, sending, or active/inactive status. Cannot change the alias address itself — delete and recreate instead.
update_bulk_migration_job_password
Update the source IMAP password for a failed job in a bulk migration batch. Only works on jobs with 'failed' status. Requires TREKMAIL_ALLOW_MIGRATION=true.
update_calendar_event
Update an existing calendar event.
update_contact
Update an existing contact's details.
update_contact_group
Rename a contact group.
update_domain_catch_all
Configure catch-all email forwarding for a domain. Unmatched emails will be forwarded to the destination. Internal targets (mailboxes on the same domain) work on all plans. External targets require Pro or Agency plan.
update_domain_note
Update the note/description on a domain (max 120 characters). Pass null to clear.
update_domain_signature
Set the per-domain email signature. mode=off disables; mode=default seeds newly-created mailbox identities; mode=enforced overrides per-mailbox signatures on the webmail compose path. Non-off modes require effective HTML after sanitization. Omit signature_html to preserve the current HTML, or pass an empty string with mode=off to clear it. Safe HTML up to 65535 characters is accepted; unsafe tags are stripped.
update_domain_smtp_profile
Update a saved SMTP profile (affects every domain using it). Omit password to keep the current one. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
update_draft
Update an existing draft by its IMAP uid and uidvalidity. Deletes the old draft only within that exact folder epoch and appends a replacement, so the response returns a NEW uid and uidvalidity pair.
update_external_account
Update a connected account (label/color/unified toggle, or new credentials/host — a connection change is re-tested). Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
update_forwarding_address
Replace the recipients of a forwarding address, pause it, or resume it. Pausing keeps the configuration and bounces mail meanwhile.
update_identity
Update name, reply-to, signature, default status, or SMTP route. When updating a connected-inbox Send As identity, pass its external_account_id so the API can enforce the exact source binding. Requires scope: messages:write.
update_mail_rule
Update an existing mail filter. Pro and Agency plans only.
update_mailbox
Update write-safe mailbox fields. display_name applies to regular and shared mailboxes. conversation_view controls webmail thread grouping for a regular mailbox and takes effect after page reload; shared mailboxes use the regular member mailbox's preference. drive_access controls whether this mailbox's user gets file storage in webmail. Does NOT touch identity (address/local_part), password, storage, or domain — use the dedicated tools for those (storage: set_mailbox_storage).
update_mailbox_note
Update the note/description on a mailbox (max 120 characters). Pass null to clear.
update_message_flags
Update flags (read/unread, starred/unstarred) on a message by IMAP UID. Requires a message token with messages:write scope.
update_message_token
Narrow an existing message API token in place: remove scopes, bring its expiry forward, or rename it. It can never gain scopes or a later expiry — create a new token for that.
update_shared_mailbox_member
Delegated dashboard roles need shared_mailboxes:write in addition to the mailboxes:write API grant; both mailboxes must be within the caller's domain and mailbox limits. Update a shared mailbox member's Read (`can_read`) and Send as (`can_send`) permissions independently; omitted fields stay unchanged. At least one of can_read, can_send or custom_label is required. Both permissions cannot be false (422 no_access_left); send-only access requires the feature (send_only_disabled) and another active reader (last_reader). Send-only members use webmail or a mail app, with no team inbox access or Message API sending. Optionally set `custom_label`, the member's personal name for the shared mailbox in their own Webmail (pass an empty string to clear it). A retryable `native_access_sync_failed` means no permission change was saved. Pass the membership row id from list_shared_mailbox_members, not the member mailbox id.
update_smtp_config
Update the SMTP configuration. Switch between platform and custom SMTP, or update custom SMTP settings. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
update_template
Update an existing email template.
update_white_label_member
Change a member's role, domains, custom permissions, or note. Omitted fields stay unchanged. Use the access catalog first; the connection cannot grant permissions broader than its own.
validate_cloudflare_token
Check if a Cloudflare API token is valid and active. Does not verify DNS permissions — use connect to test write access.
verify_cancel_job
Cancel a running verification job. Unprocessed credits are automatically refunded.
verify_credits
Check the current email verification credit balance — monthly remaining, purchased, and total available.
verify_delete_job
Permanently delete a verification job and all its results. Cannot be undone. Job must be completed or cancelled first.
verify_domain_branding_dns
Queue a DNS check + SSL provisioning for this domain's enabled branded hosts, and re-check the brand's mail zone if it has one. Run after the CNAME records (from get_domain_branding) resolve. Requires the White Label add-on — without it returns white_label_inactive. Hosts move draft/pending_dns → active once DNS resolves and the certificate is issued; poll get_domain_branding for status, including mail_zone.dns_status and mail_zone.client_hosts_status. Requires TREKMAIL_ALLOW_DESTRUCTIVE=true.
verify_email
Verify a single email address against up to 25 checks (syntax, MX, disposable, blocklist, SPF, DMARC, gibberish detection, typo suggestion, plus-addressing, DNSBL, domain age, Gravatar, unroutable MX, etc). Returns trust score 0-100 and status (safe/valid/risky/invalid). Quick mode: 1 credit (22 checks). Deep mode: 2 credits (25 checks — adds SMTP mailbox verification when available).
verify_email_bulk
Submit a list of email addresses for bulk verification. Returns a job ID to track progress. Quick mode: 1 credit/email. Deep mode: 2 credits/email. Max 50,000 emails per job.
verify_job_download
Returns the verification results as raw CSV body in the response (NOT a URL). Filters: all, safe, safe_risky. For very large jobs (>10MB) the response can be slow — consider filtering down to safe-only first.
verify_job_status
Check the progress and results of a bulk email verification job. Returns status, progress percentage, summary counts, and paginated results when complete.
verify_list_jobs
List all email verification jobs for this account with pagination. Optionally filter by status.
whoami
Verify the current API token and return token details (name, scopes, expiry) and account info.
Versions
1- 1.0.1Scanned Nov 19, 2026, 11:25 PMHigh