Reference
@chloejs/ core/ tools/ gmail
Reading, answering and sending mail, as the person signed in to Google.
The tools over gmailService.ts: reading the mail an agent is bound to, answering one of those messages, and sending one as the signed-in person.
The binding lives in the agent's config, not in anything the model can write. For reading, all the model chooses is how far back and how many. For replying, it chooses which of the messages it has already listed and what to say, and never the address.
import * as gmail from "@chloejs/core/tools/gmail";
tools: { gmailReadEmail: gmail.readEmail({ search: "in:inbox" }) }readEmailreplyEmailsendEmailSendOptions
readEmailfunction
export function readEmail({
search = "in:inbox",
what = "mail in the inbox",
days = 7,
}: Options = {})Makes a tool that lets the model read the agent's Gmail. The model lists recent messages, then can read one of them in full.
search sets which mail the model can see, and the model cannot change it.
The model chooses only how many days back (up to 365) and how many messages
(up to 50, default 10). It can open only a message that this search lists.
Needs the Google connection. If no one has signed in to Google, chloe sends the sign-in link in the chat.
tools: { gmailReadEmail: gmail.readEmail({ search: "in:inbox label:orders" }) }replyEmailfunction
export function replyEmail({
search = "in:inbox",
what = "mail in the inbox",
days = 7,
when = "",
markdown = false,
keep,
}: ReplyOptions = {})Makes a tool that lets the model reply to one of the messages it can read. The reply is sent from the signed-in Google account, in the same thread.
The model chooses the message and the words, never the address. The reply always goes to the sender of that message (or to its Reply-To address). So the model can answer people who wrote in, but cannot email anyone else. This matters because the email the model reads was written by somebody outside, and could hold instructions that try to make it write to another address.
Give it the same search as the agent's gmail.readEmail, so it can reply
to exactly the mail that tool lists.
Needs the Google connection.
sendEmailfunction
export function sendEmail(options: SendOptions)Makes a tool that lets the model send an email from the signed-in Google
account. You set the From line (from) and who it goes to (to). The model
writes only the subject and the body.
from must be the Google account's own address, or an alias Google has
verified for it. If email.provider in settings is "none", nothing is
sent: the subject is only written to the log.
Needs the Google connection.
tools: { gmailSendEmail: gmail.sendEmail({ from: "Shop <you@gmail.com>", to: ["you@gmail.com"], when: "When an order fails." }) }SendOptionsinterface
export interface SendOptions extends EmailSender {
/**
* Who the email reaches and when the model should send one, in your own
* words. Added to the tool's description for the model. Required.
*/
when: string;
/**
* A folder in the agent's memory, such as `"outbox"`. Each email sent is
* saved there as `<date>-<time>-<subject>.md` (for example
* `2026-09-23-0715-order-failed.md`), so the agent can check what it already
* said. Not set by default: no copies are kept.
*/
keep?: string;
}The options for gmail.sendEmail and resend.sendEmail. You set who sends
and who receives. The model writes only the subject and the body.