> ## Documentation Index
> Fetch the complete documentation index at: https://pomeroy.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail

> Your AI assistant can list your mailboxes, read and search your mail, and find unread messages. Pomeroy cannot send, reply, delete, move, or mark anything read.

Mail is the app with the most tools and the strictest limits. An assistant can
read everything in your mailboxes and change nothing.

<Columns cols={2}>
  <div>
    **Can**

    * List your mailboxes, with message and unread counts
    * List and read messages in any mailbox
    * Search subjects and senders, or message bodies through an index built on
      your Mac
    * List unread mail, newest first
  </div>

  <div>
    **Cannot**

    * Send a message, a reply, or a forward
    * Delete, move, or archive mail
    * Mark anything read or unread
  </div>
</Columns>

Your mailbox stays exactly as you left it. Reading a message through Pomeroy
does not mark it read.

## Tools

| Tool             | What it does                                                                                                                  | Kind |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---- |
| `mail_mailboxes` | Every mailbox with its account, message count and unread count. Start here, because the other tools take names from this list | Read |
| `mail_list`      | Messages in one mailbox, newest first: sender, subject, date, read state and the id to read one in full                       | Read |
| `mail_read`      | One message in full, by id. Long bodies are cut at 4,000 characters and the reply says so                                     | Read |
| `mail_search`    | Searches headers (subjects and senders) or message bodies. All tokens must match                                              | Read |
| `mail_unread`    | Unread messages, newest first, with the total unread count                                                                    | Read |
| `mail_index`     | Builds the local body index now and reports what it covered                                                                   | Read |

## Try it

```text theme={null}
Find the flight confirmation from March and tell me the times.
What's unread in my inbox?
Search my mail for the invoice from Northwind.
Read the last message from Priya.
How many messages are in my Archive?
```

## The content index

Searching subjects and senders is live: Pomeroy asks Mail and Mail answers.

Searching **message bodies** is different. Apple Mail has no fast way to search
body text from outside, so Pomeroy builds its own index on your Mac the first
time you ask for a content search. That first search is slow, taking minutes for
a large mailbox. Every later one answers from the index.

<Info>
  The index lives on your Mac and is never sent anywhere. It is Pomeroy's own
  bookkeeping, not your data leaving.
</Info>

Every content answer tells the assistant two things it should pass on: **how
much of your mail the index covered**, and **how old it is**. So "I found
nothing" can be reported honestly as "nothing in the 80% of your mail indexed
as of this morning", rather than as a fact about your inbox.

<Tip>
  Expecting a big search? Ask the assistant to build the mail index first, and
  pay the cost once while you do something else.
</Tip>

## Worth knowing

<AccordionGroup>
  <Accordion title="Long messages are cut at 4,000 characters" icon="scissors">
    `mail_read` truncates and says it has. This keeps one enormous newsletter
    from swallowing the conversation.
  </Accordion>

  <Accordion title="Listing does not include bodies" icon="list">
    `mail_list` returns headers and ids. An assistant reads the bodies it
    actually needs, one at a time.
  </Accordion>

  <Accordion title="Every mailbox Mail shows" icon="inbox">
    Including every account you have set up. `mail_mailboxes` is how an
    assistant discovers which ones exist, and its names are what the other tools
    take.
  </Accordion>

  <Accordion title="Sending is not available and never will be" icon="paper-plane-slash">
    There is no send tool, no reply tool and no draft tool. Mail is the app
    where a mistaken write is least recoverable and most embarrassing, so
    Pomeroy does not have the function at all.
  </Accordion>
</AccordionGroup>

## Permissions

Switching Mail on asks macOS for permission to control Mail
(`NSAppleEventsUsageDescription`). It is a separate prompt from Notes and
Shortcuts.