Tool reference

Sends markdown email. If reply_to_message_id references a message this mailbox received, the send is classified as a reply: no unsubscribe footer, same thread. Otherwise it is a cold send, which carries an unsubscribe link and is subject to the duplicate-content and velocity tripwires. Both draw down the same daily allowance.

Arguments

to string[] required

Recipient addresses.

cc string[]

Copied recipients.

subject string required

body string required

Markdown, delivered as both text and HTML.

style "plain" | "flat" | "card"

How it looks: "plain" (bare, like a person's reply), "flat" (the words and your footer on one background), or "card" (the same on a sheet, like a receipt). Omitted lets the mailbox decide, and a reply defaults to plain.

reply_to_message_id string

A message this mailbox received. Threads the send and classifies it as a reply.

attachments Attachment[]

{ filename, content_type, content_base64 }.

track_opens boolean

Off by default.

send_at string

ISO timestamp, up to 30 days out. Books the send instead of making it: everything is checked when it goes, not now.

Returns{ status: "sent" | "held" | "scheduled" | "rejected" }, with messageId, pendingId, scheduled_id, or reason and retryAfter.

{ to: string[], cc?: string[], subject: string, body: string, style?: "plain" | "flat" | "card", reply_to_message_id?: string, attachments?: Attachment[], track_opens?: boolean, send_at?: string }

Sends this agent has booked and not yet made, soonest first. Only what is still coming: one that has gone is an ordinary sent message.

Arguments

limit number

Up to 100. Defaults to 20.

Returns{ scheduled: [{ scheduled_id, subject, to, send_at, booked_at }] }

{ limit?: number }

Calls a booking off. Refused once the runner has taken it, with the status it reached, so the next step is reading what became of it rather than retrying.

Arguments

scheduled_id string required

Returns{ cancelled: true } or { error: "too_late", status, message_id?, pending_id? }

{ scheduled_id: string }

Replies keeping the whole audience: the original sender in To, the other recipients in Cc, your own address dropped. Threading is preserved, so it counts as a reply.

Arguments

message_id string required

Id of a message in this mailbox.

body string required

attachments Attachment[]

track_opens boolean

ReturnsSame shape as send_email.

{ message_id: string, body: string, attachments?: Attachment[], track_opens?: boolean }

Forwards a message. Wrapped mode keeps headers and attachments intact. Forwarding to someone who has not written to you is a cold send.

Arguments

message_id string required

Id of a message in this mailbox.

to string[] required

body string

Your note above the forwarded mail.

mode "inline" | "wrapped"

Inline quotes the original the way a person forwards mail. Wrapped attaches it untouched as a .eml. Defaults to inline.

ReturnsSame shape as send_email.

{ message_id: string, to: string[], body?: string, mode?: "inline" | "wrapped" }

Every message in a conversation at once, oldest first. Use this instead of paging list_messages when you need full context before replying.

Arguments

thread_id string required

ReturnsThread with all messages.

{ thread_id: string }

Downloads one attachment, base64 encoded.

Arguments

message_id string required

Id of a message in this mailbox.

filename string required

As listed by read_message.

Returns{ filename, content_type, size, content_base64 }

{ message_id: string, filename: string }

Lists messages newest first with sender, subject, snippet, unread flag, and spam verdict.

Arguments

unread_only boolean

thread_id string

Restrict to one conversation.

include_archived boolean

Archived mail is left out by default.

limit number

Maximum results. Defaults to 25.

ReturnsMessage summaries.

{ unread_only?: boolean, thread_id?: string, include_archived?: boolean, limit?: number }

Marks a message dealt with so it drops out of list_messages. It stays searchable and readable by id.

Arguments

message_id string required

Id of a message in this mailbox.

archived boolean

Defaults to true. Pass false to bring it back.

Returns{ id, archived_at }

{ message_id: string, archived?: boolean }

Puts a message back in the unread pile, which is how you flag something for a human after reading it.

Arguments

message_id string required

Id of a message in this mailbox.

unread boolean

Defaults to true.

Returns{ id, unread }

{ message_id: string, unread?: boolean }

Returns the full message with body and headers, and marks it read.

Arguments

message_id string required

Id of a message in this mailbox.

ReturnsFull message.

{ message_id: string }

Ranked full-text search over subjects, senders, and full bodies. Returns highlighted excerpts.

Arguments

query string required

Websearch syntax: quoted phrases, OR, -exclusions.

limit number

Maximum results. Defaults to 25.

ReturnsRanked hits with excerpts.

{ query: string, limit?: number }

Blocks until a new message arrives in the thread or the timeout elapses. Poll in a loop for longer waits.

Arguments

thread_id string required

timeout_seconds number

Up to 300. Defaults to 60.

ReturnsThe new message, or { timed_out: true }.

{ thread_id: string, timeout_seconds?: number }

The mailbox address, plan, quotas, sends left today, usage today, whether sending is unlocked, and whether this agent is paused and what it replies while it is.

Takes no arguments.

ReturnsMailbox status object.

{ }

Your handle, display name, description, inbound filter mode, and every filter rule.

Takes no arguments.

ReturnsIdentity with rules.

{ }

Changes your own presentation and how inbound mail is filtered. Omitted fields are unchanged.

Arguments

display_name string

description string

filter_mode "blacklist" | "whitelist"

ReturnsThe updated identity.

{ display_name?: string, description?: string, filter_mode?: "blacklist" | "whitelist" }

Allows or blocks a sender. An exact-address rule beats a domain rule, so you can block a domain and still let one person through. Setting the same match and value twice updates the action.

Arguments

match "exact_email" | "domain" required

value string required

An address, or a bare domain.

action "allow" | "block" required

ReturnsThe stored rule.

{ match: "exact_email" | "domain", value: string, action: "allow" | "block" }

Removes a filter rule.

Arguments

rule_id string required

Returns{ deleted: boolean }

{ rule_id: string }

The other agents you can see. Identities are hidden from each other until access is granted, so this is usually just you.

Takes no arguments.

ReturnsVisible identities.

{ }

Reverse lookup: find out who just wrote to you before deciding how to answer. Exact match first, then partial. Each hit carries the facts other agents remembered about that person.

Arguments

query string required

An email address or phone number.

limit number

Maximum results. Defaults to 25.

ReturnsContacts with channels and memories.

{ query: string, limit?: number }

Full-text search over names, company, job title, and notes.

Arguments

query string required

Websearch syntax: quoted phrases, OR, -exclusions.

limit number

Maximum results. Defaults to 25.

ReturnsRanked contacts.

{ query: string, limit?: number }

One contact in full, with every channel and all remembered context.

Arguments

contact_id string required

Contact id.

ReturnsFull contact.

{ contact_id: string }

Adds someone to the workspace address book. At least one name field is required.

Arguments

given_name string

family_name string

preferred_name string

company_name string

job_title string

channels Channel[]

{ kind: "email" | "phone", value, label? }. Passing this replaces the whole list.

domains string[]

Domains that belong to this company.

notes string

ReturnsThe created contact.

{ given_name?: string, family_name?: string, preferred_name?: string, company_name?: string, job_title?: string, channels?: Channel[], domains?: string[], notes?: string }

Omitted fields keep their value.

Arguments

contact_id string required

Contact id.

given_name string

family_name string

preferred_name string

company_name string

job_title string

channels Channel[]

{ kind: "email" | "phone", value, label? }. Passing this replaces the whole list.

domains string[]

Domains that belong to this company.

notes string

ReturnsThe updated contact.

{ contact_id: string, given_name?: string, family_name?: string, preferred_name?: string, company_name?: string, job_title?: string, channels?: Channel[], domains?: string[], notes?: string }

Deletes a contact and everything remembered about them.

Arguments

contact_id string required

Contact id.

Returns{ deleted: true }

{ contact_id: string }

Saves a durable fact. It surfaces on every later lookup of that contact, including lookups by other agents.

Arguments

contact_id string required

Contact id.

fact string required

A preference, a commitment you made, a detail worth recalling.

message_id string

The message the fact came from.

ReturnsThe stored memory.

{ contact_id: string, fact: string, message_id?: string }

Pairs that look like the same person: they share an email or phone number, or carry the same name.

Arguments

limit number

Maximum results. Defaults to 25.

ReturnsCandidate pairs with the reason.

{ limit?: number }

Folds a duplicate into the contact you keep. The survivor holds on to its own fields and gains the other one channels, remembered facts, and anything it was missing; notes from both are kept.

Arguments

survivor_id string required

The contact you keep.

loser_id string required

Deleted once merged.

ReturnsThe surviving contact.

{ survivor_id: string, loser_id: string }

Imports vCards, for example an export from Apple Contacts or Google Contacts. A bad card is skipped and reported without sinking the batch.

Arguments

vcard string required

RFC 6350 text, up to 1000 cards per call.

Returns{ imported, failed[], contact_ids[] }

{ vcard: string }

Exports one contact as an RFC 6350 vCard.

Arguments

contact_id string required

Contact id.

ReturnsvCard text.

{ contact_id: string }

Exports the whole address book as one vCard stream, ready to write to a .vcf file. Company contacts carry KIND:org so they come back as companies, not people.

Takes no arguments.

ReturnsvCard text.

{ }

Turns pasted text into contacts. Common column names are understood (email, first name, last name, name, company, title, phone, notes). A row whose email already belongs to a contact reuses that contact, so one person can sit on several lists. Rows with no email or phone are skipped and reported.

Arguments

csv string required

Pasted CSV with a header row, a headerless CSV, or one address per line ("Name <addr>" works). Up to 5000 rows.

list_name string

Put every imported contact on this list; created if it does not exist.

list_id string

Or an existing list by id.

Returns{ created, matched_existing, added_to_list, list_id, columns_understood, skipped[], contact_ids[] }

{ csv: string, list_name?: string, list_id?: string }

Every list in the workspace with its member count. Lists group people for a purpose: sales prospects, press, customers.

Takes no arguments.

ReturnsLists with member_count.

{ }

The list and a page of its members with channels and recent remembered facts. Work a list one person at a time: read them, write them a message of their own, remember what you learned. There is no send-to-list.

Arguments

list_id string required

limit number

Up to 200 per page. Defaults to 100.

offset number

Page with next_offset until it is null.

ReturnsList, member_count, next_offset, members[].

{ list_id: string, limit?: number, offset?: number }

An empty list.

Arguments

name string required

Unique per workspace, case-insensitively.

description string

ReturnsThe list.

{ name: string, description?: string }

Renames a list or changes what it is for.

Arguments

list_id string required

name string

description string

ReturnsThe list.

{ list_id: string, name?: string, description?: string }

Removes the grouping. The contacts stay in the address book.

Arguments

list_id string required

Returns{ deleted }

{ list_id: string }

Puts existing contacts on a list. Already-members are left alone.

Arguments

list_id string required

contact_ids string[] required

Up to 1000.

Returns{ added }

{ list_id: string, contact_ids: string[] }

Takes contacts off a list without deleting them.

Arguments

list_id string required

contact_ids string[] required

Returns{ removed }

{ list_id: string, contact_ids: string[] }

Notes you can read, most recently updated first.

Arguments

limit number

Maximum results. Defaults to 25.

ReturnsNote summaries.

{ limit?: number }

Full-text search across titles and bodies, with highlighted excerpts.

Arguments

query string required

Websearch syntax: quoted phrases, OR, -exclusions.

limit number

Maximum results. Defaults to 25.

ReturnsRanked hits with excerpts.

{ query: string, limit?: number }

The full note body.

Arguments

note_id string required

Note id.

ReturnsFull note.

{ note_id: string }

Writes into shared workspace context. You can always read back your own notes.

Arguments

title string

body string required

Up to 100,000 characters.

ReturnsThe created note.

{ title?: string, body: string }

Omit a field to keep it.

Arguments

note_id string required

Note id.

title string

Pass an empty string to clear it.

body string

ReturnsThe updated note.

{ note_id: string, title?: string, body?: string }

Deletes a note you can access.

Arguments

note_id string required

Note id.

Returns{ deleted: true }

{ note_id: string }

Read once before writing: the workspace brief, every indexed source with its status, and a table of contents. Facts come from search_knowledge.

Takes no arguments.

Returns{ brief, sources, pages, total_pages }

{ }

Full-text search across crawled sites, pages, and pasted text. Passages come back in full with the page they are from.

Arguments

query string required

Websearch syntax: quoted phrases, OR, -exclusions.

limit number

Up to 25. Defaults to 8.

Returns{ hits: [{ page_id, page_url, page_title, heading, body, rank }] }

{ query: string, limit?: number }

A whole indexed page, when a passage is not enough.

Arguments

page_id string required

Returns{ id, url, title, content, fetched_at }

{ page_id: string }

Every source with status, page count, and last fetch time.

Takes no arguments.

ReturnsSources.

{ }

Crawl a whole site (same domain, robots.txt honoured, up to the plan allowance), fetch one page, or store pasted text. Sites and pages index in the background.

Arguments

kind "site" | "page" | "text" required

url string

For site and page. A bare domain means https.

body string

For text. Up to 200,000 characters.

title string

ReturnsThe source, with status.

{ kind: "site" | "page" | "text", url?: string, body?: string, title?: string }

Fetch a site or page again now. Sources are refreshed weekly on their own.

Arguments

source_id string required

Returns{ id, status }

{ source_id: string }

Removes a source and every page indexed from it.

Arguments

source_id string required

Returns{ deleted: true }

{ source_id: string }

Creates a disposable address that receives mail for a short time and is then deleted along with everything it received. For signup and verification flows: register somewhere, catch the confirmation, read the code. Receive-only, and on a domain kept separate from your sending domains.

Arguments

ttl_seconds number

Up to 86400. Defaults to 600.

label string

A note to yourself, so several live addresses stay apart.

Returns{ address, expires_at, receive_only: true, remaining_slots }

{ ttl_seconds?: number, label?: string }

Blocks until mail arrives at one of your disposable addresses. Unlike wait_for_reply this is not tied to a thread, because a disposable inbox has nothing to reply to. Mail that arrived before the call is returned immediately, so triggering the email first is safe.

Arguments

address string required

timeout_seconds number

Up to 300. Defaults to 120.

ReturnsThe message, or { timed_out: true }.

{ address: string, timeout_seconds?: number }

Your disposable addresses that are still alive, soonest to expire first.

Takes no arguments.

ReturnsAddresses with their labels and expiry.

{ }

Deletes a disposable address and its mail before expiry, freeing a slot against your concurrent limit.

Arguments

address string required

Returns{ released: true }

{ address: string }

Names, types, and tags of the secrets granted to you. No values, so finding the right secret is cheaper than opening one.

Takes no arguments.

ReturnsSecret metadata.

{ }

Opens a granted secret and returns its value, so an agent can sign in or call an API without a human pasting the credential into the conversation. No key is passed: values are encrypted at rest and decrypted server-side for the agents that were granted them.

Arguments

secret_id string required

Returns{ name, type, secret }

{ secret_id: string }

The current RFC 6238 code for a login secret that carries a TOTP seed, so you can clear a two-factor prompt without a human relaying codes.

Arguments

secret_id string required

Returns{ code, expiresInSeconds }

{ secret_id: string }