# Email inboxes and sending

Give your agent its own email inboxes on a domain you own, then send email and read the replies through them with the same RouterGrowth key, over REST, the CLI or MCP. Domains and inboxes belong to your workspace. This page covers getting a domain, setting it up for sending, creating and warming up inboxes, sending and reading, the checks every send passes and the monthly fees.

To send from a Gmail or Google Workspace mailbox you already use, connect it as a [connected account](/docs/connected-accounts#gmail) instead. The [last section](#agent-inboxes-or-gmail) compares the two.

## Capabilities

| Step | Capabilities |
| --- | --- |
| See what the workspace owns (free) | `email.inboxes` |
| Get a domain | `domain.search`, `domain.register` |
| Set the domain up for sending | `email.domain`, `domain.dns` |
| Create, rename or delete an inbox | `email.inbox` |
| Warm an inbox up | `email.warmup`, `email.warmup_status` (free) |
| Send and read | `email.send`, `email.messages` |

Use [inspect](/docs/api/inspect) for each capability's current schema and price. The examples run the CLI with a live key and wait up to 30 seconds for the result; take your own `--max-cost` from `inspect`.

## Start from what you own

```bash
routergrowth run -c email.inboxes -i '{}' --wait 30
```

`email.inboxes` lists the workspace's sending domains (`domain`, `status`, `verified`, `paid_through`) and inboxes (`inbox_id`, `address`, `display_name`, `paid_through`), with a `next_step`. Run it first, so an agent picking the work up later reuses what exists. `GET /v1/email/inboxes` answers the same with an API key, plus `registered_domains`: domains bought with `domain.register` and not set up for email yet. The dashboard lists them all under **Connected accounts**.

## Get a domain

Bring any domain or subdomain you control, or buy one. Send cold email from a domain other than your main one: a deliverability problem then costs a campaign, not the mail your company runs on.

```bash
routergrowth run -c domain.search -i '{"name":"getacme","tlds":["com","io","co"]}' --max-cost 0.01 --wait 30
routergrowth run -c domain.register -i '{"domain":"getacme.com","registrant":{"first_name":"Alex","last_name":"Rivera","email":"alex@acme.com","phone":"+33612345678","address1":"10 rue de Rivoli","city":"Paris","zip":"75001","country":"FR"}}' --max-cost 25 --wait 30
```

- `domain.search`: a bare name tries `com`, `io`, `co`, `ai`, `app` and `dev`, or your `tlds`; a full domain checks that one. Each result says whether it is `available` and `premium`, with a one-year `price` and `renewal_price` as a guide.
- `domain.register`: buys the domain in RouterGrowth's registrar account with you as the registrant contact, WHOIS privacy on unless `privacy` is `false`, transferable to you on request. Every `registrant` field in the example is required (`phone` in E.164, `country` as two letters); `company` and `state` are optional. `years` is 1 to 10 (default 1), and the domain does not renew unless `auto_renew` is `true`. The registrar quotes the exact price at run time and it is held before the purchase: a price above `max_cost` is refused with `cost_limit_exceeded` before anything is bought, with the price in `details.quoted`. A purchase cannot be undone, so confirm the domain and its price with a person first.

## Set the domain up

```bash
routergrowth run -c email.domain -i '{"domain":"getacme.com"}' --max-cost 3 --wait 30
```

The first call adds the domain and returns `records`: every DNS record it needs to send and receive mail (DKIM, SPF and MX on the `mail.` subdomain that carries bounces, the MX that receives replies, DMARC), each with its `type`, `name`, `value`, `priority` and `status`, and a `next_step`. Publish the records one of three ways:

- open `setup_url`, returned when the domain's DNS provider supports one-click setup, and approve them there;
- add them at the domain's DNS provider;
- for a domain bought with `domain.register`, write them with `domain.dns`: one entry per record, `host` being the record's `name` without the domain (empty for the domain itself) and `answer` its `value`.

```bash
routergrowth run -c domain.dns -i '{"domain":"getacme.com","records":[{"type":"TXT","host":"mail","answer":"<the value email.domain returned>"}]}' --max-cost 0.01 --wait 30
```

`domain.dns` adds `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS` and `SRV` records (`ttl` 300 by default, `priority` for MX) and answers with the ones `created` and `failed`; it does not edit or delete records. Then run the same `email.domain` call again, with the same cap, until `status` is `VERIFIED`: a re-check is free, and DNS changes can take a while to show. An inbox can only be created on a verified domain.

When the domain carries no SPF record of its own, `records` also lists one for it, marked `required: false`. Mail already passes SPF through `mail.<domain>`, but warm-up health checks look for SPF on the domain itself. Add it once: a hostname must never carry two `v=spf1` records, and a domain only one DMARC record. Pass `tracking: true` on the first call to turn on open tracking; it adds a `link.<domain>` CNAME to the records.

## Create inboxes

```bash
routergrowth run -c email.inbox -i '{"name":"alex","domain":"getacme.com","display_name":"Alex Rivera"}' --max-cost 3 --wait 30
routergrowth run -c email.inbox -i '{"inbox_id":"alex@getacme.com","display_name":"Alex at Acme"}' --wait 30
routergrowth run -c email.inbox -i '{"inbox_id":"alex@getacme.com","delete":true}' --wait 30
```

`name` is the address's local part: lowercase letters, digits and hyphens (anything else becomes a hyphen), up to 32 characters. The answer's `inbox_id` is the address, which every other call takes. The same `name` and `domain` again return the existing inbox, free. `display_name` is the From name on everything the inbox sends; `email.send` has no per-email override, so rename the inbox to change it (`inbox_id` and `display_name`, free). `inbox_id` with `delete: true` hands the inbox back, free: it stops renewing, sending and receiving, and mail sent to it bounces. `email.domain` with `delete: true` does the same for a domain once no inbox is left on it.

## Warm up an inbox

A new domain has no sending reputation. `email.warmup` puts an inbox on a network of real mailboxes that send to it, open, reply and pull its mail out of spam, on a ramp to the daily volume you set, weekdays 8am to 6pm in `timezone` (IANA, `America/New_York` by default):

```bash
routergrowth run -c email.warmup -i '{"inbox_id":"alex@getacme.com","emails_per_day":20,"ramp_up":"slow","timezone":"Europe/Paris"}' --max-cost 10 --wait 30
routergrowth run -c email.warmup_status -i '{"inbox_id":"alex@getacme.com"}' --wait 30
```

- `emails_per_day` (1 to 50, default 20) is the cold volume you plan to send from the inbox. `ramp_up` is `slow` (the default, for a domain registered in the last few weeks), `normal` or `fast`. Run `start` again to change either, or the timezone.
- `action` is `start` (the default), `pause`, `resume` (which also reconnects an inbox the network lost) or `stop` (out of the network, billing ends).
- The warm-up emails are signed with the first and last name in `display_name`, or with `first_name` and `last_name` when you pass them. Mail from the network reaches the inbox too, with the warm-up's `filter_id` in its signature: skip those threads when you read replies.
- `email.warmup_status` (free) lists every warm-up with its status, volume and ramp-up day. With `inbox_id` it adds the inbox's health grade (SPF, DMARC, MX, domain age) and where its warm-up mail landed over the last 14 days, inbox or spam.

Keep cold volume at or below the warm-up volume until the ramp completes. A mailbox hosted elsewhere (Google Workspace, Microsoft 365, any SMTP host) can be warmed up too: `action: "connect"` with its address returns a one-time `connect_url` where its owner signs it in (RouterGrowth never sees the password), then `start` it like any inbox.

## Send and read

```bash
routergrowth run -c email.send -i '{"inbox_id":"alex@getacme.com","to":["jane@example.com"],"subject":"Your pricing page","text":"Hi Jane, ...","unsubscribe_url":"https://getacme.com/unsubscribe?u=jane"}' --max-cost 0.01 --idempotency-key q4-jane-1 --wait 30
routergrowth run -c email.messages -i '{"inbox_id":"alex@getacme.com","labels":["received"],"limit":20}' --max-cost 0.01 --wait 30
routergrowth run -c email.messages -i '{"inbox_id":"alex@getacme.com","message_id":"MESSAGE_ID"}' --max-cost 0.01 --wait 30
routergrowth run -c email.send -i '{"inbox_id":"alex@getacme.com","to":["jane@example.com"],"in_reply_to":"MESSAGE_ID","text":"Thanks, Tuesday works."}' --max-cost 0.01 --idempotency-key q4-jane-2 --wait 30
```

- `email.send`: up to 50 addresses in `to`, optional `cc`, `bcc` and `reply_to`, `text` or `html`, and a `subject` on a new message. `in_reply_to` takes a `message_id` and keeps the thread; the subject may be omitted, the recipients may not. `unsubscribe_url` adds a `List-Unsubscribe` header. Files go in `attachments` ([limits](/docs/api/run#attachments-on-emailsend)). The answer carries `message_id` and `thread_id`.
- `email.messages`: the inbox's mail, newest first, sent and received alike, each with `from`, `to`, `subject`, a short `preview`, `labels`, `direction` (`sent` or `received`) and `bounced` (a hard bounce is a label on your own sent message). Filter with `labels`, `from` (substrings) and `after` (ISO 8601 with a timezone); `limit` is 20 by default, 100 at most. The listing carries previews only.
- `email.messages` with `message_id`: one message in full. It adds `text`, `links`, `text_from_html` and `html` (a boolean: the message has an HTML body). `links` holds the http(s) links of the HTML body as `{text, url}`, one row per URL, 100 at most. When the email has no text part, as many signup confirmations and password resets do, `text` is the HTML body read as text, with each link written `label <url>`, and `text_from_html` is `true`. `text` stops at 20,000 characters.

Replies, deliveries, bounces, spam complaints and refused sends also arrive as [events](/docs/api/webhooks#event-types) (`email.received`, `email.delivered`, `email.bounced`, `email.complained`, `email.rejected`) on one stream for every inbox: read `GET /v1/events` instead of polling each inbox, and pass an event's `message_id` as `in_reply_to` to answer it.

## Checks on every send

- **Opt-outs and suppressions.** A person who opted out with RouterGrowth itself is blocked (`403 opted_out`). With [tables](/docs/api/tables) on, so is anyone on the workspace's [suppression list](/docs/api/tables#suppressions) (`403 suppressed`). Nothing is suppressed for you: an `email.bounced` or `email.complained` event, or a reply asking you to stop, is the cue to add the address.
- **Repeat first touch.** With tables on, a new email to someone the workspace emailed in the last 30 days is blocked (`409 repeat_touch`); replies (`in_reply_to`) and sends to your own addresses pass ([repeat first touch](/docs/api/tables#repeat-first-touch)).
- **Volume.** RouterGrowth does not pace `email.send` the way it paces LinkedIn and Instagram: the warm-up volume is the limit to keep to. A send the provider refuses for a limit comes back `provider_rate_limited`, not charged.

Each block is a `blocked` run, nothing sent or charged. You are the sender of record: consent, unsubscribe handling and the law where your recipients are (CAN-SPAM, GDPR) are yours. Give each send a unique `Idempotency-Key` (`--idempotency-key` on the CLI, `idempotency_key` on the MCP `run` tool) and reuse it when retrying the same send.

## Billing

Prices on this page are catalog prices, which start at the Scale plan rate; `inspect` returns your workspace's exact price.

- **Domains and inboxes are rented.** Adding a domain with `email.domain` and creating an inbox with `email.inbox` each charge **$1.729** for the first 30 days, then renew every 30 days from your balance until you delete them. `paid_through` on `email.inboxes` shows the paid period; the wallet ledger records each renewal as a `subscription_charge`. Status checks, listing, renaming and deleting are free; deleting refunds nothing.
- **An unpaid renewal** is skipped rather than taking the balance below zero, and tried again every hour. After 7 days unpaid, the inbox is handed back to the provider, and a domain once no inbox is left on it.
- **Calls.** `email.send` is **$0.0026** an email. `email.messages`, `domain.search` and `domain.dns` are **$0.001485** a call; a read that finds no message is free. `domain.register` is quoted by the registrar for the domain and years you ask for, from **$15.60**.
- **Warm-up** is charged per inbox for 30 days at a time, by `emails_per_day`: about $0.27 per daily email on an inbox RouterGrowth hosts (20 a day is about $5.36), about $0.16 on a mailbox connected from elsewhere (20 a day is about $3.34); connecting is free. `billing.note` on `inspect` gives your workspace's rate, and a start above `max_cost` is refused with `cost_limit_exceeded`, the charge in `details.quoted`. Raising the volume mid-period charges the prorated difference; pause and stop refund nothing; resuming after the paid period starts a new one. A warm-up whose renewal stays unpaid for 7 days is paused until you top up and resume it.

## Agent inboxes or Gmail

| | Agent inboxes (this page) | [Gmail](/docs/connected-accounts#gmail) |
| --- | --- | --- |
| Address | a new one on a domain you own, created by the API | a Gmail or Google Workspace mailbox you already use, signed in with Google OAuth |
| Monthly fee | per sending domain and per inbox | one seat per connected mailbox |
| Warm-up | `email.warmup` | `email.warmup` with `action: "connect"` |
| Sending limit | the warm-up volume you keep to | Google's sending quotas |
| Events | received, delivered, bounced, complained, rejected | received |
| Attachments | yes | not yet |
