Noiz Mail Tools Reference

Noiz Mail offers an AI app ten tools. The AI chooses which to call from what you ask, so you never need to name them, but knowing what each one can and cannot do tells you what to expect: what “find”, “file” or “send” will actually do in your mailbox. This page lists every tool with its parameters and limits, as the connector presents them today.

Last reviewed: 4 November 2026, against the live Noiz Mail connector.

How the Tools Are Marked

Each tool is marked for the AI app as read-only, a change to your mailbox, or sending. AI apps use these marks to decide when to ask you first. Sending is marked as needing your approval and its description tells the AI to confirm with you; most apps then show you the message before it goes. Changes such as flagging, moving and saving a draft are not marked that way and may happen without a prompt.

Every tool takes an optional mailbox parameter naming one of the mailboxes in your connection. Without it, the first mailbox you connected is used. Folder names are given as your mail app shows them, for example INBOX, Sent or Clients/Acme.

Read-Only Tools

mail_accounts

Lists the mailboxes connected in this session, in the order they were connected. The first is the default for every other tool. No parameters.

mail_folders

Lists the folders of one mailbox with message and unread counts, the special roles (inbox, sent, drafts, trash, junk), any shared or other-users folders your mail server exposes, and your access rights on shared folders.

Parameter	Meaning
mailbox	Which mailbox; default the first connected

Counting stops after 60 seconds on a very large mailbox, but every folder is still listed.

mail_search

Searches one folder, every folder, or every mailbox, newest first. Returns one row per message with its uid, date, sender, subject, flags and size; the content comes from mail_read.

Parameter	Meaning
folder	Folder to search; default INBOX. * searches every folder except Trash and Junk
text	Words anywhere in the message
from_, to, subject	Match those headers
since, before	Dates as YYYY-MM-DD
unread, flagged	True or false to filter by flag
limit	Rows to return, 1 to 100; default 25
offset	Rows to skip, for paging
mailbox	One mailbox, or * for every mailbox in the connection

Limits: with folder="*", offset plus limit may be at most 1,000, at most 100 folders are visited and no new folder is started after 60 seconds (the rest are counted in not_searched). With mailbox="*", each row carries the mailbox it came from, offset plus limit may be at most 500, no new mailbox is started after 45 seconds, and mailboxes that could not be searched are listed in errors with the reason.

mail_read

Reads one message: headers, the plain text (HTML is converted to text and hidden text is left out), the link targets found in it, and the list of attachments with their index numbers.

Parameter	Meaning
folder, uid	Which message, from a search row
mailbox	Which mailbox

The body is cut at 50,000 characters and the result says so when that happens.

mail_thread

Finds the other messages in the same conversation, looking in the same folder and in Sent.

Parameter	Meaning
folder, uid	The message to start from
mailbox	Which mailbox

mail_attachment

Returns one attachment. Plain text and PDF come back as text the AI can read; any other type comes back as base64 data.

Parameter	Meaning
folder, uid	Which message
index	Which attachment, from the mail_read list
mailbox	Which mailbox

Limit: attachments over 5 MB cannot be opened. Scanned PDFs, Office documents and pictures contain no readable text, so the AI may not be able to read them.

Tools That Change Your Mailbox

mail_flag

Marks messages read or unread, flagged or unflagged, or answered.

Parameter	Meaning
folder, uids	One or more messages
seen, flagged, answered	True to set, false to clear, leave out to keep
mailbox	Which mailbox

mail_move

Moves, or copies, messages to another folder that already exists. Noiz Mail never creates folders and never deletes mail permanently.

Parameter	Meaning
folder, uids	One or more messages
destination	An existing folder name, or trash, archive or junk for the mailbox’s own folder of that role
copy	True to copy instead of move
mailbox	Which mailbox

“Delete” in your AI app becomes a move to Trash, where you can restore the message until Trash is emptied.

mail_draft

Saves a draft in the Drafts folder, as a new message or as a threaded reply.

Parameter	Meaning
to, cc	Recipients
subject	For a new draft only; a reply keeps the original subject with “Re:”
text	The plain-text body
html	An HTML body; images with an https address or a data URI are embedded in the message, other image sources are refused
reply_to_folder, reply_to_uid	Makes the draft a threaded reply to that message
replace_draft_uid	Replaces an earlier draft; the old one moves to Trash
mailbox	Which mailbox

Sending

mail_send

Sends a new message, a reply or a forward, always from the signed-in address of the mailbox in use. A copy is saved in Sent; if the copy cannot be saved, the message still goes and the AI is told.

Parameter	Meaning
to, cc, bcc	Recipients. For a reply, to is not used: it goes to the original sender, or to everyone with reply_all
subject	For a new message only; a reply or forward keeps the original subject with “Re:” or “Fwd:”
text	The plain-text body
html	An HTML body for a new message or reply; images as for mail_draft. A forward is plain text
reply_to_folder, reply_to_uid	Reply to that message
reply_all	Reply to everyone on the original
forward_folder, forward_uid	Forward that message to to
mailbox	Which mailbox

The tool is marked as needing your approval and tells the AI to confirm with you before sending. See Security and Privacy for what that means in each app.

Limits That Apply to Every Tool

A connection runs at most four tool calls at once; a fifth waits its turn and is told the connection is busy if no slot comes free in 30 seconds. Each call waits its turn for a session on your mail server, and a call that cannot get one within 30 seconds is told the server is busy and asks you to try again shortly. Nothing is changed in either case. The full list is in Limits and Behaviour.