Tools
Every tool airpost-mcp exposes, with its parameters and the access level it needs.
This is the list an MCP client gets from tools/list. Each tool’s description, which the agent reads, is reproduced here. The Access line is the lowest access level that allows the tool; hidden accounts and folders apply to every tool.
Recipient lists (to, cc, bcc, attendees) are arrays of {name?, email} objects. Dates without an offset are read in the local time zone of the machine running airpost-mcp.
Results and errors
Every tool returns one text content block holding pretty-printed JSON. On failure the block is {"error": "<message>"} and the result has isError: true:
{"error": "Access denied: 'send' operations require access level 'read-write-send', but current level is 'read-write'."}
Timestamps in results are ISO 8601 in UTC (2026-11-12T16:04:11.000Z). Ids are opaque strings; take them from earlier results. The examples under each group below are trimmed and the ids are shortened.
Mail: reading
list_accounts
List all email accounts configured in Airpost
Access: Read mail (read-only)
No parameters.
list_folders
List all folders/labels for an email account. Each entry includes a role — a provider-agnostic identifier (e.g. “inbox”, “sent”, “drafts”, “trash”, “spam”, “archive”, “all”, “important”, “snoozed”) for standard folders, or null for user-created ones. Use role rather than name to find a standard folder like Sent or Trash, since the display name varies by provider (e.g. “Sent Mail” vs “Sent Items” vs Gmail’s SENT label).
Access: Read mail (read-only)
The account ID to list folders for
search_mail
Search for email threads, in Airpost’s search bar grammar. Plain words must all match somewhere in the thread (sender, recipients, subject, folder names or body), each as a word prefix; “quoted phrases” match together. Fields: from:<text>, to:<text>, subject:<text>, in:<folder> (a standard role such as in:inbox, in:sent, in:drafts, in:trash, in:spam, in:archive works across providers; otherwise a folder/label name or path), is:unread|read|starred|unstarred, has:attachment, before:<date> and after:<date> (or since:). Dates: 2026-05-31 or 2026/05/31, “may 31 2026”, month or weekday names, today, yesterday, “3 days ago”, 3d/2w/6m/1y, “last week|month|year”; after: includes its day, before: excludes it, both in the user’s time zone. Terms are combined with AND unless joined by OR; NOT x excludes x (e.g. ‘budget NOT in:trash’); parentheses group. Examples: ‘in:sent project alpha’, ‘from:alice is:unread’, ‘(from:bob OR from:carol) has:attachment after:2026/01/01’. Each result’s lastMessageReceivedTimestamp orders the list, newest first.
Access: Read mail (read-only)
Search query string
Optional account ID to scope the search
Max results to return (default 150)
Number of results to skip for pagination (default 0)
list_threads
List threads in a specific folder/label. To find a standard folder like Sent or Trash, call list_folders first and pick the entry whose role matches (“inbox”, “sent”, “drafts”, “trash”, “spam”, “archive”, “all”, “important”, “snoozed”) — the exact folder name varies by provider, so don’t guess it from name.
Access: Read mail (read-only)
The account ID
The folder/label ID (from list_folders — match by role for standard folders)
Max results (default 25)
Offset for pagination
Filter to unread only
get_thread
Get a thread with all its messages, full body content, and attachment metadata (each message’s files array; retrieve one with get_attachment). Each message has draft: true for the user’s own unsent drafts, which are not mail anyone received.
Access: Read mail (read-only)
The thread ID
get_message
Get a single message with full body content and attachment metadata (files array; retrieve one with get_attachment). draft is true for the user’s own unsent drafts.
Access: Read mail (read-only)
The message ID
get_attachment
View the contents of an email attachment. Find the attachment’s fileId in the files array returned by get_message or get_thread (use search_mail’s has:attachment to find mail with attachments). Every result starts with a JSON metadata block (filename, contentType, size, plus the file’s local path and its MCP resourceUri — this server only runs on the same machine, so the path is directly readable by local tools). Text-based attachments (text/*, JSON, XML, SVG, ICS, EML) up to 200KB include their content in the JSON as UTF-8 data; images (PNG/JPEG/GIF/WebP) up to 200KB are additionally returned as an MCP image content block so they can be viewed directly; any other type or size returns no inline payload — instead the result ends with a resource_link content block whose URI can be fetched via resources/read, or the file can be read straight from path. If the attachment hasn’t been downloaded from the mail server yet it is fetched first, which can take several seconds.
Access: Read mail (read-only)
The attachment’s file ID (from the message’s files array)
The ID of the message the attachment belongs to
list_templates
List the user’s email templates (Airpost’s Preferences > Templates): each one’s name, subject, variables (the blanks to fill in) and the start of its text. With name, that template with its whole HTML body. Write a draft from one with create_draft or reply_to_thread’s template, or fill its variables in the body and pass that as body.
Access: Read mail (read-only)
A template’s name, to get its body
Tracking and scheduled sends
get_message_tracking
Get open-tracking and link-tracking data for a single sent message: total open count, per-recipient open timestamps, and per-link click counts with per-recipient click timestamps.
Access: Read mail (read-only)
The message ID
list_tracked_messages
List sent messages that have open-tracking and/or link-tracking enabled, along with their open/click data. Use sentAfter/sentBefore to bound by send date (e.g. “everything sent this month”) and openedAfter to filter by when the open/click activity itself happened (e.g. “opened today”). Answers questions like “which of my emails have been opened today” or “every email I sent this month with link tracking”.
Access: Read mail (read-only)
Restrict to a single account
Max results to return (default 50)
Only include messages with at least this many total link clicks
Only include messages with at least this many total opens
Offset for pagination
ISO 8601 date - only include messages with an open or link-click event at/after this time (filters on activity time, not send date)
ISO 8601 date - only messages sent after this
ISO 8601 date - only messages sent before this
Only include messages with open-tracking, link-tracking, or either (default) One of opens, links, either.
get_top_links
Rank links from link-tracking-enabled sent messages by total click count, across a time range. Answers questions like “what are my highest performing links” or “which links get clicked the most”.
Access: Read mail (read-only)
Restrict to a single account
Max number of links to return (default 10)
ISO 8601 date - only consider messages sent after this
ISO 8601 date - only consider messages sent before this
list_scheduled_sends
List drafts with a “Send Later” schedule. state is scheduled (sendAt is in the future), due (sendAt passed and the draft hasn’t gone out yet: being sent, waiting for the draft’s body, or Airpost wasn’t running) or failed (Airpost gave up; error says why and the draft stays unsent until it is rescheduled or sent).
Access: Read mail (read-only)
Restrict to a single account
Drafts and sending
create_draft
Create a new email draft (does not send it). Airpost adds the From address, the user’s signature and their composing defaults, so write only the message. The result has the draft’s id and headerMessageId (for update_draft, delete_draft, send_draft and schedule_send) and its attachments.
Access: Read and draft (read-write)
Recipients
Account ID to send from (uses default if omitted)
Files on this computer to attach, by absolute path. Their contents go out with the draft when it is sent, so attach only files the user asked for. At most 25 MB in all; a file the draft already has (same name and contents) isn’t attached twice. Not available when Airpost is reached over HTTP
BCC recipients
Email body (HTML). Give this or template
CC recipients
Remind the user if no one has replied this many days after the draft is sent (fractions allowed): Airpost brings the thread back to the top of the inbox then Greater than 0, at most 365.
Email subject (optional with a template that has one)
Name of one of the user’s Airpost templates (list_templates) to write the draft from, instead of body: its text goes above the signature, and its subject unless subject is given. Its variables stay as the template wrote them; to fill them, read the template with list_templates {name} and pass the filled-in text as body instead
Track clicks on the message’s links. Needs a Airpost server that offers tracking; fails otherwise
Track when recipients open the message. Needs a Airpost server that offers tracking; fails otherwise
reply_to_thread
Create a reply draft in a thread (does not send it). It replies to the newest message in the thread that is not a draft (or to messageId), quoting it and addressing its sender (and, for reply-all, its other recipients). The result lists the thread’s existing unsent drafts: to change a reply you already drafted, call update_draft on it instead of creating another.
Access: Read and draft (read-write)
Thread ID to reply to
Files on this computer to attach, by absolute path. Their contents go out with the draft when it is sent, so attach only files the user asked for. At most 25 MB in all; a file the draft already has (same name and contents) isn’t attached twice. Not available when Airpost is reached over HTTP
Reply body (HTML). Give this or template
Optional ID of the message in the thread to reply to (not a draft); defaults to the newest received or sent message
Remind the user if no one has replied this many days after the draft is sent (fractions allowed): Airpost brings the thread back to the top of the inbox then Greater than 0, at most 365.
Name of one of the user’s Airpost templates (list_templates) to write the draft from, instead of body: its text goes above the signature, and never its subject: a reply keeps “Re:”. Its variables stay as the template wrote them; to fill them, read the template with list_templates {name} and pass the filled-in text as body instead
Track clicks on the message’s links. Needs a Airpost server that offers tracking; fails otherwise
Track when recipients open the message. Needs a Airpost server that offers tracking; fails otherwise
Reply type (default: reply) One of reply, reply-all.
update_draft
Edit an existing draft: change its subject, body, or To/Cc/Bcc, attach files from this computer or remove attachments. The draft keeps its identity (id, headerMessageId, thread, the message it replies to, the attachments not removed). Use this to revise a reply drafted with reply_to_thread. Drafts that are being sent or scheduled can’t be edited.
Access: Read and draft (read-write)
Optional account ID the draft belongs to
Files on this computer to attach, by absolute path. Their contents go out with the draft when it is sent, so attach only files the user asked for. At most 25 MB in all; a file the draft already has (same name and contents) isn’t attached twice. Not available when Airpost is reached over HTTP
New BCC recipients; replaces the current ones
New body (HTML). Replaces the whole body, including any quoted text, so include the quote when keeping it
New CC recipients; replaces the current ones
The draft’s headerMessageId; used when id is not given
The draft’s message id (from get_thread, or the result of create_draft / reply_to_thread)
Remind the user if no one has replied this many days after the draft is sent (fractions allowed): Airpost brings the thread back to the top of the inbox then Greater than 0, at most 365.
Attachments to remove: file ids or filenames from the draft’s files (get_thread or get_message)
New subject
New recipients; replaces the current ones
Track clicks on the message’s links. Needs a Airpost server that offers tracking; fails otherwise
Track when recipients open the message. Needs a Airpost server that offers tracking; fails otherwise
delete_draft
Delete an unsent draft. A pending scheduled send of the draft is cancelled with it; a draft that is being sent can’t be deleted.
Access: Read and draft (read-write)
Optional account ID the draft belongs to
The draft’s headerMessageId; used when id is not given
The draft’s message id (from get_thread, or the result of create_draft / reply_to_thread)
send_draft
Send a draft now, by its headerMessageId. A send can’t be called back: show the user the draft and get an explicit yes first.
Access: Read, draft and send (read-write-send)
The headerMessageId of the draft to send
schedule_send
Schedule an existing draft to be sent automatically at a future date/time, equivalent to the “Send Later” composer button. The Airpost engine sends it at that time with no window open (the result’s note says when the desktop app must send it instead: an older engine, or an actionKey other than send / send-and-archive). Use cancel_scheduled_send to undo, and list_scheduled_sends to see whether it went out or failed.
Access: Read, draft and send (read-write-send)
The headerMessageId of the draft to schedule
ISO 8601 date-time in the future to send the draft at; without an offset it is local time
Optional send action key to use when the draft is sent (defaults to send). The engine performs send and send-and-archive; other keys are plugin actions the desktop app performs
cancel_scheduled_send
Cancel a pending “Send Later” schedule on a draft so it will not be sent automatically. Errors if the draft has no active schedule.
Access: Read and draft (read-write)
The headerMessageId of the draft
set_reminder
Set or clear a send reminder on a thread, as Airpost’s reminder menu does: if no one has replied by then, Airpost brings the thread back to the top of the inbox. Use it on a thread the user sent the last message in; for a draft, give remindInDays to create_draft, reply_to_thread or update_draft instead.
Access: Read and draft (read-write)
The thread
true to remove the thread’s reminder instead
Days from now (fractions allowed) Greater than 0, at most 365.
Threads
archive_threads
Archive one or more threads
Access: Read and draft (read-write)
Thread IDs to archive
trash_threads
Move one or more threads to trash
Access: Read and draft (read-write)
Thread IDs to trash
move_to_folder
Move threads to a specific folder
Access: Read and draft (read-write)
Target folder ID
Thread IDs to move
set_labels
Add or remove labels from threads (Gmail only)
Access: Read and draft (read-write)
Thread IDs
Label IDs to add
Label IDs to remove
create_label
Create a label on a Gmail account, as Airpost’s label picker does, and wait until the server has it. The result’s labelId goes to set_labels. / nests a label under another (Work/Clients). Fails when the account doesn’t use labels or already has one by that name; list_folders shows the existing ones.
Access: Read and draft (read-write)
The Gmail account to create the label on
The label’s name
set_unread
Mark threads as read or unread
Access: Read and draft (read-write)
Thread IDs
true to mark unread, false to mark read
set_starred
Star or unstar threads
Access: Read and draft (read-write)
true to star, false to unstar
Thread IDs
snooze_threads
Snooze threads until a date/time, as the app’s Snooze menu does: they move out of the inbox to Snoozed and come back to the top of the inbox at that time (the Airpost engine brings them back by itself). Use unsnooze_threads to bring them back early.
Access: Read and draft (read-write)
Thread IDs to snooze
ISO 8601 date-time in the future to bring the threads back at; without an offset it is local time
unsnooze_threads
End the snooze of threads now: those still in Snoozed move back to the inbox.
Access: Read and draft (read-write)
Thread IDs to unsnooze
undo
Take back the last change this assistant made through Airpost: archive_threads, trash_threads, move_to_folder, set_labels, set_unread, set_starred or snooze_threads (their results carry an undo token naming the change). Only this assistant’s own changes: what the user did in Airpost is theirs to undo. With redo, make an undone change again. Creating labels and sending can’t be undone here.
Access: Read and draft (read-write)
Make the last undone change (or the token’s) again instead
The undo token of the change, from that tool’s result; the latest change without it
unsubscribe
Unsubscribe from the mailing list a message came from, using its List-Unsubscribe header: the engine makes the one-click request (RFC 8058) when the list offers it, otherwise sends the unsubscribe email. When the list only has a web page, the result’s url must be opened by the user in a browser; tell them. Fails when the message has no List-Unsubscribe header.
Access: Read, draft and send (read-write-send)
ID of a message from the list
Use only this way (default: the best the list offers) One of one-click, mailto, web.
Calendar
list_events
Calendar events between two times, every occurrence of a repeating event, oldest first. Each has eventId (for update_event and respond_to_event), title, start and end (ISO 8601; all-day events have startDate/endDate as YYYY-MM-DD, end exclusive), isRecurring, organizer, attendees and myStatus.
Access: Read mail (read-only)
ISO 8601 date-time
ISO 8601 date-time; without an offset it is local time
Only this account (default: every enabled account)
Only these calendars
create_event
Create a calendar event. With attendees the account is the organizer and the server mails them invitations, which needs the read-write-send access level.
Access: Read and draft (read-write); with attendees, or on a meeting with guests the account organizes, Read, draft and send
The calendar (a calendarId from list_events, or ask the user)
ISO 8601 date-time
ISO 8601 date-time
Guests; the calendar server invites them by mail
An RFC 5545 RRULE value, e.g. FREQ=WEEKLY;BYDAY=MO;COUNT=10
update_event
Change or delete a calendar event. For a repeating event, scope says which occurrences: ‘this’ (one, named by occurrenceStart), ‘following’ (that one and the ones after) or ‘all’. Only the fields given change; attendees replaces the guest list. Changing or deleting a meeting the account organizes that has guests, or giving attendees, needs read-write-send, as the server mails the guests.
Access: Read and draft (read-write); with attendees, or on a meeting with guests the account organizes, Read, draft and send
Guests; the calendar server invites them by mail
Delete the occurrences the scope covers
ISO 8601 date-time
ISO 8601 start of the occurrence, for scope this or following
Default: all One of this, following, all.
ISO 8601 date-time
respond_to_event
Answer an invitation (accepted, tentative or declined): the answer is written to the user’s copy and mailed to the organizer. With proposedStart and proposedEnd it proposes another time to the organizer instead, and changes nothing.
Access: Read, draft and send (read-write-send)
One of accepted, tentative, declined.
Answer only this occurrence of a repeating event (ISO 8601 start)
ISO 8601 date-time
ISO 8601 date-time
Contacts
get_contact
A contact’s details: name, emailAddresses, phoneNumbers, addresses, company, title, birthdays, urls, notes, and whether it can be edited (contacts found only in mail can’t).
Access: Read mail (read-only)
A contact id (from create_contact; mail participants carry addresses, not contact ids)
create_contact
Add a contact to the account’s address book (CardDAV, or Google Contacts on a Google account).
Access: Read and draft (read-write)
Required when several accounts are enabled
Full name, ‘Given Family’
update_contact
Change a contact; the fields given replace the stored ones (email and phone replace the whole list with that one value). Other details on the card are kept.
Access: Read and draft (read-write)
Resources
Attachments are also served as the resource template attachment://{messageId}/{fileId} (“Email attachment”). get_attachment returns the URI as resourceUri; read it with resources/read to get the raw bytes. resources/read calls are written to the audit log too.