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

# Email

> Read incoming email, send a new message, and reply from your agent's address.

Set up the agent's email channel in [Artil](https://app.artil.dev), then sign
the CLI in as that agent. Run `artil auth status` to see its address and channel state.
If a command reports an access error, see
[message troubleshooting](/troubleshooting#email-or-sms-is-unavailable).

You can also use this address to [sign up for services](/email-identity).

## 1. List incoming email

```bash theme={null}
artil email
artil email list --limit 10
```

For a first test, send an email from your own account to the agent's address.
If the inbox is empty, allow time for delivery and list it again.

The list shows incoming messages, newest first, and the address where the agent
can be reached. `--limit` accepts 1 to 25; the default is 25. If the agent has
multiple email addresses, they share one inbox.

## 2. Read a message

```bash theme={null}
artil email read "mail:<message-id>"
```

Use the ID printed by the list. The `mail:` prefix is optional in `email`
commands. SMS message IDs return an error here.

The output includes the message body and any attachment names, types, and
sizes. These commands do not download attachment contents.

## 3. Reply

```bash theme={null}
artil email send --reply-to "mail:<message-id>" -- "Thanks, I will take a look."
```

A reply uses the original message to choose its recipient and thread. It
inherits the subject with a `Re:` prefix and uses the address the message
arrived at when that mailbox is still available. If that address is no longer
available, it uses the agent's primary address.

You can override the recipient with `--to` or the subject with `--subject`.

Check your own inbox for the reply.

<Card title="Next: connect a client to this inbox" href="/setup">
  Use Claude Code, Pi, or Hermes to read messages and reply from this address.
</Card>

## Send a new email

```bash theme={null}
artil email send --to teammate@example.com --subject "Build results" -- "The build passed."
```

A new message needs a recipient and subject and leaves from the agent's primary
address. Repeat `--to` for multiple recipients, up to ten:

```bash theme={null}
artil email send --to alice@example.com --to bob@example.com --subject "Build results" -- "The build passed."
```

The message body is plain text. These commands have no attachment, CC, or BCC
flags. Bodies are limited to 32,000 characters and subjects to 240 characters.

## Check the result

A successful send prints the channel, recipients, and message ID after
submission to the email service. To confirm delivery, check the recipient's
inbox. Keep the ID to read the sent message later; the inbox list shows
incoming messages only.

If a send fails or is interrupted and its outcome is unknown, check with the
recipient before trying again to avoid sending a duplicate.

## Use JSON in a script

```bash theme={null}
artil email list --limit 10 --json
artil email read "mail:<message-id>" --json
```

`list`, `read`, and `send` support `--json`. Message data is inside `result`.
Check the exit status before using that field: failed commands exit with a
nonzero status, and access errors can return a different JSON structure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.