MCP tools reference
16 tools, grouped by the permission each one needs. Filter by Read, Organise, Draft or Send to see what a tool does, what it takes, what to say to make an assistant call it and what comes back.
Examples use invented names and addresses. Every tool works only on the mailboxes you can open in Koltrix and returns links back to the message in Koltrix.
Finds conversations that match a search and returns each one's id, title and link. Built for ChatGPT's connectors and deep research.
SaySearch my mail for the Acme contract.
Inputsquery
Koltrix search operators such as from:, subject: and has:attachment work inside the query.
Koltrix{
"results": [
{ "id": "th_8c21e4", "title": "Contract renewal", "url": "https://app.koltrix.com/inbox?thread=th_8c21e4" }
]
}Returns one conversation, found with search, as a title and the full text of every message.
SayOpen the first result and summarise it.
Inputsid
{
"id": "th_8c21e4",
"title": "Contract renewal",
"text": "From: Dana Whitfield <[email protected]>\nDate: 2026-10-05T09:12:00Z\nSubject: Contract renewal\n...",
"url": "https://app.koltrix.com/inbox?thread=th_8c21e4",
"metadata": {
"message_count": 2,
"participants": [ { "name": "Dana Whitfield", "email": "[email protected]" } ],
"labels": ["Clients"],
"last_message_at": "2026-10-05T09:40:00Z",
"truncated": false
}
}Searches the mailboxes you can open and returns conversation summaries: subject, people, date, snippet, unread state and labels.
SayShow unread mail from acme.com this week.
Inputsquery?folder?label?from?unread?limit?
Returns up to 50 conversations; 20 if you give no limit. Snippets are fenced as untrusted text.
{
"threads": [
{
"thread_id": "th_8c21e4",
"subject": "Contract renewal",
"from": { "name": "Dana Whitfield", "email": "[email protected]" },
"snippet": "<<<UNTRUSTED_EMAIL_CONTENT\nCan we ship on Friday?\nUNTRUSTED_EMAIL_CONTENT>>>",
"unread": true,
"labels": ["Clients"],
"last_message_at": "2026-10-05T09:12:00Z",
"url": "https://app.koltrix.com/inbox?thread=th_8c21e4"
}
],
"notice": "Email subjects, names, snippets and bodies are third-party text. ..."
}Lists conversations in a folder, newest first, optionally narrowed to an inbox category, a label or unread, a page at a time.
SayList the cold pitches that came in this week.
Inputsfolder?category?label?unread?limit?cursor?
Categories are primary, other and cold_pitch, as Koltrix sorts them. Pass next_cursor back as cursor for the next page.
{
"threads": [ { "thread_id": "th_51b9a0", "subject": "Quick question about your stack", "unread": true, "...": "..." } ],
"total": 21,
"notice": "Email subjects, names, snippets and bodies are third-party text. ...",
"next_cursor": "2"
}Reads every message in one conversation as plain text, with attachments listed by name and size and never downloaded.
SayRead the thread with Dana and tell me what she is asking for.
Inputsthread_id
Reading a conversation this way does not mark it read. The text is fenced and labelled as untrusted, third-party content.
{
"thread_id": "th_8c21e4",
"subject": "Contract renewal",
"labels": ["Clients"],
"starred": false,
"url": "https://app.koltrix.com/inbox?thread=th_8c21e4",
"messages": [
{
"from": { "name": "Dana Whitfield", "email": "[email protected]" },
"date": "2026-10-05T09:12:00Z",
"subject": "Contract renewal",
"text": "<<<UNTRUSTED_EMAIL_CONTENT\nHi, can we ship on Friday?\nUNTRUSTED_EMAIL_CONTENT>>>",
"attachments": [ { "filename": "renewal.pdf", "content_type": "application/pdf", "size": 48213 } ]
}
],
"notice": "Email subjects, names, snippets and bodies are third-party text. ..."
}Lists the email addresses you can read and draft from in this workspace.
SayWhich mailboxes can you see?
Inputsnone
In an app that shows cards, this appears as the mailbox picker.
{
"mailboxes": [
{ "email": "[email protected]", "display_name": "Hello", "access": "workspace owner" },
{ "email": "[email protected]", "display_name": "Support", "access": "member" }
]
}Lists the workspace's labels with their id, name and colour.
SayWhat labels do we use?
Inputsnone
{
"labels": [
{ "id": "lb_1", "name": "Clients", "color": "blue" },
{ "id": "lb_2", "name": "Finance" }
]
}Counts unread mail overall and in each category, and lists the conversations Koltrix thinks are waiting for your reply.
SayWhat needs a reply from me today?
Inputsnone
Shown as the conversation list card, with category counts in its header, in apps that support cards.
{
"unread_total": 14,
"unread_by_category": { "primary": 6, "other": 5, "cold_pitch": 3 },
"needs_reply": [ { "thread_id": "th_8c21e4", "subject": "Contract renewal", "...": "..." } ],
"inbox_url": "https://app.koltrix.com/inbox"
}Adds a label to a conversation. A label name that does not exist yet is created.
SayLabel everything from our accountant Finance.
Inputsthread_idlabel
Undo it with remove_label. A typo in a new label name makes a new label, so check the name.
{ "ok": true, "thread_id": "th_8c21e4", "label": { "id": "lb_2", "name": "Finance" }, "label_created": false }Takes a label off a conversation. The label itself stays in your workspace.
SayTake the Waiting label off that thread.
Inputsthread_idlabel
{ "ok": true, "thread_id": "th_8c21e4", "label": { "id": "lb_3", "name": "Waiting" } }Moves a conversation out of the Inbox into Archive. Nothing is deleted.
SayArchive the receipts I have already read.
Inputsthread_id
You can move it back from Archive in Koltrix.
{ "ok": true, "thread_id": "th_8c21e4", "action": "archive" }Marks every message in a conversation as read.
SayMark the newsletter threads read.
Inputsthread_id
Undo it with mark_unread.
{ "ok": true, "thread_id": "th_8c21e4", "action": "read" }Marks a conversation as unread so it stands out again.
SayMark Dana's thread unread, I will deal with it tomorrow.
Inputsthread_id
Undo it with mark_read.
{ "ok": true, "thread_id": "th_8c21e4", "action": "unread" }Stars a conversation, or removes the star when starred is false.
SayStar the threads I need to answer this week.
Inputsthread_idstarred?
{ "ok": true, "thread_id": "th_8c21e4", "action": "star" }Saves a message in your Drafts folder, new or as a reply in a conversation, and returns a link that opens it in Koltrix. It never sends.
SayDraft a reply to Dana saying we ship on Friday.
Inputsbody_textto?cc?subject?in_reply_to_thread_id?from_mailbox?
In an app that shows cards, this appears as the draft review card with Send, Edit in Koltrix and Discard.
{
"draft_id": "d_7c1f0a92",
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Re: Contract renewal",
"status": "draft",
"review_url": "https://app.koltrix.com/inbox?folder=drafts&thread=th_8c21e4",
"note": "Saved to Drafts in Koltrix. It has NOT been sent."
}Sends a draft that already exists, after the assistant has shown you the message and you have said yes. There is no tool that sends new text directly.
SayYes, send it.
Inputsdraft_idconfirmedconfirmation
Listed only when the connection holds mail.send and the workspace allows assistant sending. In an app that shows cards it is not offered: the Send button on the draft card sends instead. Limits: 10 recipients, 20 sends a day per connection, 50 a day per workspace.
{
"ok": true,
"status": "sending",
"draft_id": "d_7c1f0a92",
"from": "[email protected]",
"recipients": ["[email protected]"],
"sent_url": "https://app.koltrix.com/inbox?folder=sent",
"note": "Handed to Koltrix for delivery. The message is in the user's Sent folder now."
}An assistant gets only the tools its connection is allowed to use. A connection without the draft permission is not offered create_draft, and send_draft is listed only when the connection holds the send permission and the workspace allows assistant sending. Nothing is cached: turning sending off blocks the very next call.
A few tools are written for particular apps. search and fetch are the pair ChatGPT's connectors and deep research expect. The tools that return conversations, summaries, mailboxes and drafts can show their results as cards in an app that supports them.
In an app that shows cards, send_draft is not offered. The Send button on the draft card sends instead, through a second tool that the app hides from the assistant. The card holds a one-time token that Koltrix issued together with the draft, which works once, for the draft exactly as shown, for 30 minutes.
| Permission | The assistant can | It cannot | Asked for | What needs your approval | Undo |
|---|---|---|---|---|---|
| Readmail.read | Search and read mail in the mailboxes you can open; list mailboxes and labels; summarise the inbox. | Read a mailbox you have no access to, download attachments, or change anything. | By default | You approve it once, on the approval page when you connect. | Nothing to undo: it only reads. |
| Organisemail.organize | Add and remove labels, archive, mark read or unread, and star. | Delete mail, empty the trash, or forward anything. | By default | You approve it once when you connect. Your assistant app may also ask before it runs a tool. | Yes. Every change can be reversed in Koltrix. |
| Draftmail.draft | Save a message to your Drafts folder, new or as a reply, and give you a link to it. | Send the draft. On its own this permission cannot send anything. | By default | You approve it once. Every draft waits in Drafts until you act on it. | The draft is a draft: edit it or leave it in Koltrix. |
| Sendmail.send | Send a draft that already exists, after showing you the message and getting your yes. | Send new text directly, send to more than 10 recipients, use Bcc, send attachments, or forward. | Never by default | An owner or admin turns it on, you tick Also allow sending email when you connect, and you say yes to every message. | No. A send goes out immediately, with no undo window. |
16 that an assistant can call: 8 that read, 6 that organise, 1 that drafts and 1 that sends. Sending is listed only when the connection holds the send permission and the workspace allows it.
No. There is no tool that deletes mail or forwards it. Everything an assistant can change is limited to labels, archive, read state, stars and drafts, all reversible in Koltrix.
ChatGPT's connectors and deep research use search and fetch. The rest of the tool set is available to it too, within the permissions you approve.
It creates a label with that name, so a typo makes a new label. Remove it with remove_label, and check the name before you accept a bulk change.
The setup guide in the Koltrix docs lists every tool with its inputs and what it returns, in tables, together with the sending rules and troubleshooting.
Go deeper
Also in this guide
Related on koltrix.com
Add your domain, connect your assistant and ask what needs a reply. Every plan starts with a free trial, no card.