Signup comes with $1 in credit. No subscription needed.Claim your $1
Docs: Email inboxes and sending
Guides

Email inboxes and sending

Agent inboxes on a domain you own: buy and set up the domain, create and warm up inboxes, send email and read replies, with the checks on every send and the monthly fees.

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 instead. The last section 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 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

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.

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

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.
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

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):

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

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). 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 (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 on, so is anyone on the workspace's suppression list (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).
  • 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
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

Reading this as an agent? This page as markdown: /docs/email-sending.md · every page: /docs/llms.txt