# Email

How an agent sends, receives, replies to and forwards email from the inbox of its account, and how you put that inbox on a domain of your own. What the inbox is and what it costs is on [Services](/services).

## Before you start

The agent needs an account whose inbox is `ready`. [Getting started](/docs/getting-started) opens one. The examples use `acct_123` for the account id.

## Add an inbox to an account that has none

An account opened without an inbox can be given one later. From an AI client, say so:

```text
Add an inbox to the assistant account.
```

The client calls `stack_add_account_piece` with the piece `inbox`. The same from code or the terminal:

```typescript
await stack.accounts.addPiece('acct_123', { piece: 'inbox' }, { idempotencyKey: 'add-inbox-acct-123' });
```

```bash
npx @getstackrun/cli account add-piece acct_123 --piece inbox --idempotency-key add-inbox-acct-123
```

- Only the owner or an admin can add a piece. An agent cannot.
- The first inbox of your account is included. A further inbox is charged from the wallet, and needs the wallet to hold its first month: otherwise the answer is 402 INSUFFICIENT_BALANCE and nothing is added.
- To put the inbox on your own verified domain, give the domain: stack_add_account_piece with inbox.domain, or --domain on the command.
- The inbox shows as pending and then ready. A retry with the same idempotency key is the same add. An account that already has an inbox answers 409.

## Send an email

From an AI client, say what to send:

```text
Email the invoice summary to anna@example.com from the assistant account, and copy me.
```

The client calls `stack_send_account_email`. The same send from code or the terminal:

```typescript
import { Stack } from '@getstackrun/sdk';

const stack = new Stack();
const sent = await stack.accounts.sendEmail('acct_123', {
  to: 'anna@example.com',
  cc: ['you@example.com'],
  subject: 'Invoice summary',
  body: 'The three open invoices come to 4,200 EUR.',
});
// sent.message_id, sent.thread_id, sent.status
```

```bash
npx @getstackrun/cli account send-email acct_123 \
  --to anna@example.com --subject "Invoice summary" --body "The three open invoices come to 4,200 EUR."
```

- to takes one address or a list. cc and bcc take lists. An email needs at least one to.
- The mail provider takes one To address. The first to is the To, and further to addresses are delivered as Cc.
- One email is one action, however many people it reaches.
- Any agent of yours can send from the inbox, unless you set it to read only. It sends under its own Passport, so its own limits apply.

## Read what arrives

```text
List the email the assistant account received today.
```

The client calls `stack_list_account_messages`, then `stack_get_account_message` for one message. From code: `stack.accounts.messages.list('acct_123', { channel: 'email' })`. From the terminal: `account messages acct_123 --channel email`.

- Your agents can read each other's messages, on every channel. A read of another agent's messages is recorded, without the content.
- stack_search_messages searches the messages of all your agents at once, by agent, channel, sender, recipient, thread, time or text.
- stack_read_message_attachment reads a file that arrived with a message.
- You decide what agents may do with messages: stack_set_message_access, or message-access set --read-teammates false to keep each agent to its own messages, and --read-only true to stop an agent sending. Name an agent to set it for that agent only. Only the owner or an admin can.

Received mail is content from outside, and so is every file attached to it. STACK scans it and flags likely attacks on every account. With controls on, flagged mail is withheld from the agent unless you choose to have it delivered with its flag.

## Reply and forward

A reply names the received email by its message id (`amsg_...`) and goes to the person who wrote it, in the same thread, quoting the original.

```typescript
await stack.accounts.replyEmail('acct_123', 'amsg_abc', { body: 'Thanks, received.' });

await stack.accounts.forwardEmail('acct_123', 'amsg_abc', {
  to: 'finance@example.com',
  body: 'For your records.',
});
```

- reply_all: true also reaches everyone the original was sent to.
- A forward goes as a new email in no thread, with the attachments that were kept.
- The tools are stack_reply_account_email and stack_forward_account_email. The CLI commands are account reply-email and account forward-email.

## Attach files

Attach a file from the agent's drive by its id, or a small file inline. Files that arrive with an email are saved to the receiving agent's drive, so a received file can be attached to the next email by the `file_id` on the message.

```typescript
await stack.accounts.sendEmail('acct_123', {
  to: 'anna@example.com',
  subject: 'Signed contract',
  body: 'Attached.',
  attachments: [{ file_id: 'drv_0123456789abcdef' }],
});
```

Inline files come to at most 10 MB in all. For a larger file, upload it to the drive first.

## Start the agent when mail arrives

Mail is stored when it arrives, and nothing starts the agent until a rule says so. Set one rule and each new email wakes the agent with a task:

```text
When email arrives for the assistant account from @example.com, wake the agent to read and answer it.
```

The client calls `stack_set_wake_rule` with `source: "email"`. Each wake is one action. The task text is yours; nothing the sender wrote is part of it.

## Use your own domain

A new inbox is on STACK's shared domain. To send from your own, verify the domain once, then open accounts on it. You need to be the owner or an admin.

```bash
# 1. Connect the domain. The answer lists the DNS records to publish.
npx @getstackrun/cli account mail-domain-connect --domain mail.example.com

# 2. Publish the records at your DNS provider, then ask for the check.
npx @getstackrun/cli account mail-domain-verify omd_abcdefgh1234

# 3. See every domain and its status.
npx @getstackrun/cli account mail-domains
```

When the domain is verified, open an account on it:

```typescript
await stack.accounts.open(
  { name: 'assistant', inbox: { domain: 'mail.example.com' } },
  { idempotencyKey: 'open-assistant-1' },
);
```

A domain left unverified for 7 days can be connected by another customer.

## When a send is refused

- 403 MESSAGES_READ_ONLY - you set this agent to read only. It cannot send, reply or forward.
- 429 SHARED_MAIL_DAILY_LIMIT - the day's recipients on the shared domain are used up. Nothing was sent. Wait for the next UTC day or use your own domain.
- 413 EMAIL_ATTACHMENTS_TOO_LARGE - the attachments pass what the mail provider takes in one email. Send fewer files or a share link.
- 422 EMAIL_MESSAGE_NOT_ANSWERABLE - the message id is not an email the account received, or the email was withheld.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused the send. The answer names the rule.
- A paused inbox sends nothing. The owner lifts the pause with stack_resume_account_piece.

## Reference

Every field of the send, reply and forward calls is on [Messages, Mail and Texts](/docs/api/account-messaging). Every tool is in the [tool reference](/docs/mcp-tools).
