---
title: Mail
description: "The owner's Gmail, read live, with drafting and sending. 4 tools."
group: mail
tools: [mail.search, mail.read, mail.draft, mail.send]
source: [packages/agents/src/tools/integrations.ts, packages/agents/src/tools/writes.ts, packages/integrations/src/catalog.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

The owner's own mail, read live from every Gmail account they connected through Roadstar. Nothing is copied unless the owner turns on [search](/tools/search/).

- `search` and `read` work on every connected account.
- `draft` makes a draft in the owner's Gmail and sends nothing.
- `send` sends from the owner's Gmail. It is checked first, and it leaves after a two-minute Undo on Home.

Drafting and sending need the owner's connection to allow writing. Until it does, they return error `reauth`, and a card asks the owner to connect again. See [errors](/reference/errors/).

`attach` takes Drive files by id (Google files go as PDFs), attachments by their id from search, and workspace files by path, 25 MB in all.

Where search is on, `search` and `read` here cover only what search's copy doesn't hold yet. Once every account is copied whole, mail keeps only `draft` and `send`, and its how-to says so.

## How to use it

What `find_tools` sends with these tools, word for word:

> The owner's mail, such as Gmail, searched live. A thread reads as its messages without quoted text; attachments read like files. Gmail's web links don't open here: search by sender and subject. Gmail: Gmail's query takes its search box syntax, and results come back newest first.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [mail.search](#search) | Threads, newest first, across the owner's mail accounts, each with everyone on it but the owner; query takes the mail's own search words, such as in:sent; dates as YYYY-MM-DD. nextPage, passed as page, gives older threads | No |
| [mail.read](#read) | A thread's messages with sender, recipients, date and text, and its attachments. With an attachment's id, that file's text. | No |
| [mail.draft](#draft) | Make a draft in the owner's Gmail, in its thread when replying. Sends nothing. | No |
| [mail.send](#send) | Send an email from the owner's Gmail. It goes after a two-minute Undo. | Checked |

## search

`mail.search` · Threads, newest first, across the owner's mail accounts, each with everyone on it but the owner; query takes the mail's own search words, such as in:sent; dates as YYYY-MM-DD. nextPage, passed as page, gives older threads.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `query` | text | no |  | up to 500 characters |
| `from` | text | no |  | up to 200 characters |
| `to` | text | no |  | up to 200 characters |
| `after` | text | no |  | up to 40 characters |
| `before` | text | no |  | up to 40 characters |
| `hasAttachment` | true or false | no |  |  |
| `source` | text | no | Only accounts whose name contains this, e.g. an email address | up to 120 characters |
| `limit` | whole number | no |  | 1–20, default 10 |
| `page` | text | no |  | up to 4,000 characters |

Returns:

```ts
{
  nextPage?: string;
  hits: (Hit & {
    source: string;
  })[];
  searched: string[];
  failed: Failure[];
}
```

## read

`mail.read` · A thread's messages with sender, recipients, date and text, and its attachments. With an attachment's id, that file's text.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `id` | text | yes | 3–500 characters |
| `attachment` | text | no | up to 300 characters |
| `offset` | whole number | no | 0 or more |

Returns:

```ts
Content & {
  id: string;
  source: string;
  nextOffset?: number;
}
```

## draft

`mail.draft` · Make a draft in the owner's Gmail, in its thread when replying. Sends nothing.

**Owner's yes:** No. It makes something new.\
**Your work:** listed on Home.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `to` | list of email address | no |  | up to 20 items, each up to 200 characters, default [] |
| `cc` | list of email address | no |  | up to 20 items, each up to 200 characters |
| `subject` | text | yes |  | up to 300 characters |
| `text` | text | yes |  | up to 20,000 characters |
| `threadId` | text | no | To reply in a thread: its id from search | up to 300 characters |
| `replyAll` | true or false | no | Answer everyone on the thread |  |
| `attach` | list of `{ file }` or `{ email?, attachment }` or `{ workspace }` | no | Drive files (Google files go as PDFs), attachments by their id from search, or workspace files by path, 25 MB in all | up to 10 items |
| `signature` | true or false | no | false leaves off the owner's Gmail signature |  |

Returns:

```ts
{
  draftId: string;
  threadId: string;
  to: string[];
}
```

## send

`mail.send` · Send an email from the owner's Gmail. It goes after a two-minute Undo.

**Owner's yes:** Checked. It sends outside the business. It can also carry a note for the check to weigh.\
**Your work:** listed on Home, with Undo.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `to` | list of email address | no |  | up to 20 items, each up to 200 characters, default [] |
| `cc` | list of email address | no |  | up to 20 items, each up to 200 characters |
| `subject` | text | yes |  | up to 300 characters |
| `text` | text | yes |  | 1–20,000 characters |
| `threadId` | text | no | To reply in a thread: its id from search | up to 300 characters |
| `replyAll` | true or false | no | Answer everyone on the thread |  |
| `attach` | list of `{ file }` or `{ email?, attachment }` or `{ workspace }` | no | Drive files (Google files go as PDFs), attachments by their id from search, or workspace files by path, 25 MB in all | up to 10 items |
| `signature` | true or false | no | false leaves off the owner's Gmail signature |  |

Returns:

```ts
{
  held: {
    trigger: number;
    at: string;
    to: string[];
  };
  threadId: string;
  note: string;
}
```

## Types

Named types in the results above.

```ts
type Hit = {
  id: string;
  title: string;
  type: string;
  who?: string;
  people?: string[];
  date?: string;
  snippet?: string;
  url: string;
}

type Failure = {
  source: string;
  kind: "not_connected" | "reauth" | "forbidden" | "not_found" | "rate_limited" | "unavailable" | "too_large" | "unsupported" | "bad_input" | "vendor" | "changed" | "unknown_outcome";
  message: string;
  integration: string;
  connection: string;
}

type Content = {
  title: string;
  url: string;
  text: string;
  attachments?: Attachment[];
  items?: Hit[];
  nextPage?: string;
  image?: {
    mimeType: string;
    data: string;
  };
  note?: string;
}

type Attachment = {
  id: string;
  name: string;
  size: number;
}
```