Every tool an agent can call, 29 in all. An agent sees only the tools its rights allow; the right each tool needs is named the way it reads on the Agents screen.
This page is generated from the server itself with
scripts/docs-tools.py.
mail_boxes
Mailboxes. List the mailboxes this agent may use: id, address, name, the person's access, and folders.
Needs: Mail, search and read. Reads only.
mail_search
Search mail. Search messages, newest first. query takes words and Gmail-like operators: from:, to:, cc:, subject:, has:attachment, is:unread, is:read, is:flagged, newer_than:7d, older_than:1m, after:2026-01-31, before:2026-02-28, in:sent. Without a query it lists the latest messages. Returns ids for mail_read and mail_thread.
Needs: Mail, search and read. Reads only.
| Parameter | Type | What it is |
|---|---|---|
box | string | Only this mailbox: its address or id (see mail_boxes) |
folder | all · inbox · sent · archive · drafts · spam · trash · flagged · anywhere | Where to look; all = everything except spam, trash and drafts (default) |
limit | integer | How many to return |
offset | integer | Skip this many, to page through results |
query | string | Words and operators, e.g. "invoice from:olga newer_than:30d" |
unread | boolean | Only unread messages |
mail_read
Read a message. Open one message by id: sender, recipients, date, subject, plain text and the list of attachments. Reading does not mark it as read unless mark_read is true (needs the organize right).
Needs: Mail, search and read. Reads only.
| Parameter | Type | What it is |
|---|---|---|
id (required) | integer | Message id from mail_search |
mark_read | boolean | Also mark it as read; needs the organize right |
max_chars | integer | Cut the text at this many characters |
mail_update
Organize messages. Archive, trash, mark spam or not spam, return to the inbox, mark read or unread, flag or unflag, add or remove a label, or move to a folder. Several message ids at once; for move, all must be in one mailbox.
Needs: Mail, and organize: archive, flags, labels. Changes data.
| Parameter | Type | What it is |
|---|---|---|
action (required) | archive · trash · spam · not_spam · inbox · read · unread · flag · unflag · label · unlabel · move | What to do with the messages |
folder | string | Folder name or role (archive, inbox…), for move |
ids (required) | array | Message ids from mail_search |
label | string | Label name, for label and unlabel |
mail_draft
Write a draft. Save an email as a draft in the mailbox: the person finds it in Drafts and sends it themselves. To reply, pass reply_to with the message id: recipient, subject and threading are filled in. The mailbox signature is added unless signature is false.
Needs: Mail, and write drafts. Changes data.
| Parameter | Type | What it is |
|---|---|---|
bcc | string | Blind copy recipients, comma-separated |
box | string | From which mailbox: address or id (see mail_boxes). When replying, the mailbox of the message. |
cc | string | Copy recipients, comma-separated |
reply_to | integer | Id of the message this answers |
signature | boolean | Add the mailbox signature |
subject | string | When replying, defaults to Re: and the subject of the message. |
text (required) | string | Plain-text body |
to | string | Recipients, comma-separated. When replying, defaults to the sender of the message. |
mail_send
Send an email. Send an email. Unless this agent may send on its own, the email waits for the person's approval in mailrust (the result says so): tell the person. Counts against the agent's daily limit. To reply, pass reply_to with the message id.
Needs: Mail, and send emails. Changes data, can delete.
| Parameter | Type | What it is |
|---|---|---|
bcc | string | Blind copy recipients, comma-separated |
box | string | From which mailbox: address or id (see mail_boxes). When replying, the mailbox of the message. |
cc | string | Copy recipients, comma-separated |
reply_to | integer | Id of the message this answers |
signature | boolean | Add the mailbox signature |
subject | string | When replying, defaults to Re: and the subject of the message. |
text (required) | string | Plain-text body |
to | string | Recipients, comma-separated. When replying, defaults to the sender of the message. |
mail_thread
Read a conversation. The whole conversation a message belongs to, oldest first, each message without the quoted text of earlier ones.
Needs: Mail, search and read. Reads only.
| Parameter | Type | What it is |
|---|---|---|
id (required) | integer | Any message id of the conversation |
max_chars | integer | Per message |
Contacts
contacts_search
Search contacts. Find people in the address book by name, address or company. Without a query, the people written to most often.
Needs: Contacts, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
limit | integer | How many to return |
query | string | A part of the name, the address or the company |
contacts_save
Save a contact. Add a person to the address book or change one: name, company and notes for an email address.
Needs: Contacts, view and change. Changes data.
| Parameter | Type | What it is |
|---|---|---|
company | string | Where they work |
email (required) | string | The person's address; the contact is found or created by it |
name | string | The person's name |
notes | string | A note about them |
Calendar
calendar_events
Calendar events. Events between two moments (ISO 8601). By default, the next 14 days.
Needs: Calendar, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
from | string | ISO 8601, e.g. 2026-10-20 or 2026-10-20T09:00:00+03:00 |
to | string | ISO 8601, the end of the period |
calendar_add
Add an event. Put an event in the person's own calendar. No one is invited: to invite people, write to them with mail_send.
Needs: Calendar, view and change. Changes data.
| Parameter | Type | What it is |
|---|---|---|
location | string | Where: an address or a call link |
minutes | integer | How long it lasts |
start (required) | string | ISO 8601 with time zone, e.g. 2026-10-20T15:00:00+03:00 |
title (required) | string | What the event is |
Tasks
tasks_list
Tasks. The person's tasks: open by default, or done. Each with its due time and the email it came from, if any.
Needs: Tasks, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
done | boolean | true: done tasks instead of open ones |
limit | integer | How many to return |
tasks_add
Add a task. Add a task, optionally due at a moment and tied to an email (message id): the task then leads back to it.
Needs: Tasks, view and change. Changes data.
| Parameter | Type | What it is |
|---|---|---|
due | string | ISO 8601 date or moment |
message | integer | Message id the task comes from |
notes | string | Details for the task |
title (required) | string | What to do |
tasks_update
Change a task. Mark a task done or not done, or change its title, due time or notes.
Needs: Tasks, view and change. Changes data.
| Parameter | Type | What it is |
|---|---|---|
done | boolean | Mark it done or open again |
due | string | ISO 8601; empty string removes the due time |
id (required) | integer | Task id from tasks_list |
notes | string | New details for the task |
title | string | A new title |
Outreach
outreach_campaigns
Outreach campaigns. Cold outreach campaigns the person can see: id, name, goal, status, how many prospects in each state, and whether the person owns it or works in someone else's.
Needs: Outreach, view. Reads only.
outreach_campaign
Outreach campaign. One campaign: its email sequence (steps with delays, subjects and texts), funnel stages with counts, and prospects by state.
Needs: Outreach, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
campaign (required) | integer | Campaign id from outreach_campaigns |
outreach_prospects
Campaign prospects. Prospects of a campaign, optionally only in one state (waiting, writing, replied, hold, later, lost, or stage1…stageN) or matching a word in address, site or name.
Needs: Outreach, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
campaign (required) | integer | Campaign id from outreach_campaigns |
limit | integer | How many to return |
query | string | Only prospects whose address, site or name contains this |
state | string | waiting, writing, replied, hold, later, lost, stage1…; empty: all |
outreach_add
Add prospects. Add up to 100 prospects to a campaign: email and/or site, name, and fields used as {{variables}} in the emails. Someone already in the campaign is updated, not duplicated; addresses on the stop list are not added. New prospects get emails by the campaign's own rules.
Needs: Outreach, work with prospects. Changes data.
| Parameter | Type | What it is |
|---|---|---|
campaign (required) | integer | Campaign id from outreach_campaigns |
prospects (required) | array | The people to add, up to 100 |
outreach_update
Update a prospect. Record what happened with a prospect: replied, agreed, lost (with a reason), stop (never write again), later (come back in N days); and/or move to a funnel stage, set the deal value.
Needs: Outreach, work with prospects. Changes data.
| Parameter | Type | What it is |
|---|---|---|
campaign (required) | integer | Campaign id from outreach_campaigns |
days | integer | For later |
email (required) | string | Prospect address (or site) |
reason | string | For lost: one of the campaign's reasons, e.g. price, timing, competitor, declined |
stage | integer | Funnel stage number |
state | replied · agreed · lost · stop · later | What happened: replied, agreed (won), lost, stop (never write again), later (come back in some days) |
value | integer | Deal value in the campaign currency |
outreach_step
Edit a sequence step. Write or change one email of the campaign's sequence: position (1 = first email), delay in days after the previous one, subject (empty = reply in the same thread) and text. Use {{name|there}}, {{company}}, {{site}} and other prospect fields. Only the campaign owner can do this.
Needs: Outreach, manage campaigns. Changes data.
| Parameter | Type | What it is |
|---|---|---|
body (required) | string | The email text, with {{variables}} |
campaign (required) | integer | Campaign id from outreach_campaigns |
delay_days | integer | Days after the previous email |
position (required) | integer | Which email of the sequence: 1 is the first |
subject | string | Empty: a reply in the same thread |
outreach_control
Start or pause a campaign. Start a campaign (after the same pre-launch check a person gets: blockers stop it) or pause it. Starting sends real emails to real people. Only the campaign owner can do this.
Needs: Outreach, manage campaigns. Changes data, can delete.
| Parameter | Type | What it is |
|---|---|---|
action (required) | start · pause | start sends real emails after the pre-launch check; pause stops sending |
campaign (required) | integer | Campaign id from outreach_campaigns |
Newsletters
mailings_lists
Newsletter lists. The person's newsletter lists: id, key, name, how many are subscribed, pending, unsubscribed, and whether joining needs email confirmation.
Needs: Newsletters, view. Reads only.
mailings_subscribers
Subscribers. Subscribers of a list: address, name, status, tags, fields; optionally only one status (active, pending, left, bounced) or matching a word.
Needs: Newsletters, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
limit | integer | How many to return |
list (required) | string | List id or key from mailings_lists |
query | string | Only subscribers whose address or name contains this |
status | string | active, pending, left, bounced; empty: all |
mailings_issues
Newsletter issues. Issues of a list with their numbers: sent, opened, clicked, unsubscribed, bounced.
Needs: Newsletters, view. Reads only.
| Parameter | Type | What it is |
|---|---|---|
list (required) | string | List id or key from mailings_lists |
mailings_subscribe
Subscribe a person. Subscribe an address to a list the way the list's own form would: if the list needs confirmation, the person gets a confirmation email first.
Needs: Newsletters, manage subscribers. Changes data.
| Parameter | Type | What it is |
|---|---|---|
email (required) | string | The address to subscribe |
list (required) | string | List id or key from mailings_lists |
name | string | The person's name, used as {{name}} in emails |
tags | array | Tags that later decide who gets an issue |
mailings_unsubscribe
Unsubscribe a person. Unsubscribe an address from a list.
Needs: Newsletters, manage subscribers. Changes data.
| Parameter | Type | What it is |
|---|---|---|
email (required) | string | The address to unsubscribe |
list (required) | string | List id or key from mailings_lists |
mailings_issue_draft
Prepare an issue. Prepare a newsletter issue as a draft from blocks: heading, text (blank lines between paragraphs, bold, words), button, image, divider. The person reviews and sends it from mailrust; nothing is sent now.
Needs: Newsletters, prepare issues. Changes data.
| Parameter | Type | What it is |
|---|---|---|
blocks (required) | array | The email from top to bottom, up to 60 blocks |
list (required) | string | List id or key from mailings_lists |
preheader | string | The line mail apps show after the subject |
subject (required) | string | The issue's subject |
Insights
analytics_report
Analytics. Numbers for a period, the same as the Analytics screen: mail (received, answered, response time), team (shared mailboxes), outreach (sent, replies, meetings, deals), mailings (sent, opens, clicks, unsubscribes), delivery, sites (API emails), assist (AI usage). Each figure comes with the previous period of the same length.
Needs: Analytics, sees analytics. Reads only.
| Parameter | Type | What it is |
|---|---|---|
days | 7 · 30 · 90 · 365 | Length of the period, in days, ending today |
section | mail · team · outreach · mailings · delivery · sites · assist | Which part of the Analytics screen |
delivery_status
Deliverability. The state of the person's sending domains: MX, SPF, DKIM, DMARC, MTA-STS, TLS-RPT, BIMI and blacklist listings. Set check to true to check a domain again now (takes a few seconds).
Needs: Deliverability, sees deliverability. Reads only.
| Parameter | Type | What it is |
|---|---|---|
check | boolean | Check the domain again now instead of returning the last check |
domain | string | Only this domain |