Airpost
MCP server

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.

Some tools need a recent Airpost engine. On an older one they fail with an error that says to update Airpost.

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)

accountIdstringrequired

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)

querystringrequired

Search query string

accountIdstring

Optional account ID to scope the search

limitnumberdefault:150

Max results to return (default 150)

offsetnumberdefault:0

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)

accountIdstringrequired

The account ID

folderIdstringrequired

The folder/label ID (from list_folders — match by role for standard folders)

limitnumberdefault:25

Max results (default 25)

offsetnumberdefault:0

Offset for pagination

unreadboolean

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)

threadIdstringrequired

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)

messageIdstringrequired

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)

fileIdstringrequired

The attachment’s file ID (from the message’s files array)

messageIdstringrequired

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)

namestring

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)

messageIdstringrequired

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)

accountIdstring

Restrict to a single account

limitnumberdefault:50

Max results to return (default 50)

minClicksnumber

Only include messages with at least this many total link clicks

minOpensnumber

Only include messages with at least this many total opens

offsetnumberdefault:0

Offset for pagination

openedAfterstring

ISO 8601 date - only include messages with an open or link-click event at/after this time (filters on activity time, not send date)

sentAfterstring

ISO 8601 date - only messages sent after this

sentBeforestring

ISO 8601 date - only messages sent before this

trackingTypestringdefault:either

Only include messages with open-tracking, link-tracking, or either (default) One of opens, links, either.

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)

accountIdstring

Restrict to a single account

limitnumberdefault:10

Max number of links to return (default 10)

sentAfterstring

ISO 8601 date - only consider messages sent after this

sentBeforestring

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)

accountIdstring

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)

toobject[]required

Recipients

accountIdstring

Account ID to send from (uses default if omitted)

attachmentsstring[]

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

bccobject[]

BCC recipients

bodystring

Email body (HTML). Give this or template

ccobject[]

CC recipients

remindInDaysnumber

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.

subjectstring

Email subject (optional with a template that has one)

templatestring

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

trackLinksboolean

Track clicks on the message’s links. Needs a Airpost server that offers tracking; fails otherwise

trackOpensboolean

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)

threadIdstringrequired

Thread ID to reply to

attachmentsstring[]

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

bodystring

Reply body (HTML). Give this or template

messageIdstring

Optional ID of the message in the thread to reply to (not a draft); defaults to the newest received or sent message

remindInDaysnumber

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.

templatestring

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

trackLinksboolean

Track clicks on the message’s links. Needs a Airpost server that offers tracking; fails otherwise

trackOpensboolean

Track when recipients open the message. Needs a Airpost server that offers tracking; fails otherwise

typestringdefault:reply

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)

accountIdstring

Optional account ID the draft belongs to

attachmentsstring[]

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

bccobject[]

New BCC recipients; replaces the current ones

bodystring

New body (HTML). Replaces the whole body, including any quoted text, so include the quote when keeping it

ccobject[]

New CC recipients; replaces the current ones

headerMessageIdstring

The draft’s headerMessageId; used when id is not given

idstring

The draft’s message id (from get_thread, or the result of create_draft / reply_to_thread)

remindInDaysnumber

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.

removeAttachmentsstring[]

Attachments to remove: file ids or filenames from the draft’s files (get_thread or get_message)

subjectstring

New subject

toobject[]

New recipients; replaces the current ones

trackLinksboolean

Track clicks on the message’s links. Needs a Airpost server that offers tracking; fails otherwise

trackOpensboolean

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)

accountIdstring

Optional account ID the draft belongs to

headerMessageIdstring

The draft’s headerMessageId; used when id is not given

idstring

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)

headerMessageIdstringrequired

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)

headerMessageIdstringrequired

The headerMessageId of the draft to schedule

sendAtstringrequired

ISO 8601 date-time in the future to send the draft at; without an offset it is local time

actionKeystring

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)

headerMessageIdstringrequired

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)

threadIdstringrequired

The thread

clearboolean

true to remove the thread’s reminder instead

remindInDaysnumber

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)

threadIdsstring[]required

Thread IDs to archive

trash_threads

Move one or more threads to trash

Access: Read and draft (read-write)

threadIdsstring[]required

Thread IDs to trash

move_to_folder

Move threads to a specific folder

Access: Read and draft (read-write)

folderIdstringrequired

Target folder ID

threadIdsstring[]required

Thread IDs to move

set_labels

Add or remove labels from threads (Gmail only)

Access: Read and draft (read-write)

threadIdsstring[]required

Thread IDs

labelsToAddstring[]

Label IDs to add

labelsToRemovestring[]

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)

accountIdstringrequired

The Gmail account to create the label on

namestringrequired

The label’s name

set_unread

Mark threads as read or unread

Access: Read and draft (read-write)

threadIdsstring[]required

Thread IDs

unreadbooleanrequired

true to mark unread, false to mark read

set_starred

Star or unstar threads

Access: Read and draft (read-write)

starredbooleanrequired

true to star, false to unstar

threadIdsstring[]required

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)

threadIdsstring[]required

Thread IDs to snooze

untilstringrequired

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)

threadIdsstring[]required

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)

redoboolean

Make the last undone change (or the token’s) again instead

tokenstring

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)

messageIdstringrequired

ID of a message from the list

methodstring

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)

endstringrequired

ISO 8601 date-time

startstringrequired

ISO 8601 date-time; without an offset it is local time

accountIdstring

Only this account (default: every enabled account)

calendarIdsstring[]

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

calendarIdstringrequired

The calendar (a calendarId from list_events, or ask the user)

endstringrequired

ISO 8601 date-time

startstringrequired

ISO 8601 date-time

titlestringrequired
accountIdstring
allDayboolean
attendeesobject[]

Guests; the calendar server invites them by mail

descriptionstring
locationstring
recurrenceRulestring

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

eventIdstringrequired
accountIdstring
attendeesobject[]

Guests; the calendar server invites them by mail

deleteboolean

Delete the occurrences the scope covers

descriptionstring
endstring

ISO 8601 date-time

locationstring
occurrenceStartstring

ISO 8601 start of the occurrence, for scope this or following

scopestring

Default: all One of this, following, all.

startstring

ISO 8601 date-time

titlestring

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)

eventIdstringrequired
statusstringrequired

One of accepted, tentative, declined.

accountIdstring
commentstring
occurrenceStartstring

Answer only this occurrence of a repeating event (ISO 8601 start)

proposedEndstring

ISO 8601 date-time

proposedStartstring

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)

contactIdstringrequired

A contact id (from create_contact; mail participants carry addresses, not contact ids)

accountIdstring

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)

accountIdstring

Required when several accounts are enabled

companystring
emailstring
namestring

Full name, ‘Given Family’

notesstring
phonestring
titlestring

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)

contactIdstringrequired
accountIdstring
companystring
emailstring
namestring
notesstring
phonestring
titlestring

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.