---
name: email-outreach
description: Set up cold email outreach for the customer — a SmartLead client account, sending mailboxes on a warmed-up domain, and the mailboxes wired to that account. Use when the user asks to "set up email outreach", "start cold emailing", "get me sending cold emails", "set up SmartLead", or wants sending mailboxes/domains provisioned for outreach. This is the parent skill: it explains the whole picture and what it costs; the actual work is done by its three child skills.
required_environment_variables:
  - ADVISORREACH_API_URL
  - ADVISORREACH_API_KEY
---

# Email Outreach (overview)

This skill explains what "setting up email outreach" means end to end, what it
costs, and how long each part takes. It does not itself call any API — it hands
off to three child skills, each of which does one part of the work:

- **`email-outreach-client`** — creates the customer's SmartLead client account
  (or reuses one that already exists) and retrieves its login credentials.
- **`email-outreach-mailboxes`** — finds and orders sending mailboxes on a domain
  (this is the part that spends money).
- **`email-outreach-connect`** — assigns ordered mailboxes to the client account
  so they are actually usable for sending.

Read this skill before any of the three children — it carries the retry
contract and the cost picture that all three depend on. Each child also says
this explicitly, in case you land on one directly.

## What the customer ends up with

A SmartLead client account, dedicated sending domain(s), and one or more
mailboxes on those domains, all connected to that account — ready to run cold
email campaigns from. This is infrastructure, not a finished campaign: getting
there does not by itself send any email.

## Order of operations

1. `email-outreach-client` — get or create the SmartLead client account.
2. `email-outreach-mailboxes` — search for a vendor/domain and order mailboxes.
   **This step costs real money — see below. Never do it without telling the
   customer the price first and getting them to confirm.**
3. `email-outreach-connect` — assign the ordered mailboxes to the client account.

Do these in order. Steps 2 and 3 both need a client account to exist first.

## Timing — say this plainly, do not let the customer expect it sooner

- **Mailbox delivery** (the mailbox actually existing and reachable after
  ordering) takes **around 8 hours**. It is not instant, and it is not
  something you can poll faster by trying more often.
- **Domain/mailbox warmup** — the period before a new mailbox is trusted enough
  by inboxes to send real outreach reliably — takes **weeks**, not days. This
  happens automatically after mailboxes are connected; there is nothing further
  for you to do to speed it up, and no API call confirms "warmup is done" —
  just tell the customer to expect it.

Never imply either step is done sooner than the API confirms, and never imply
warmup is a one-time step you completed rather than an ongoing period the
mailbox is still going through.

## What it costs

- **Client account creation** can purchase a SmartLead seat at **$29/month** if
  the account does not already have a free seat available. It is idempotent by
  email — see the retry contract below — but the money aspect is real and
  child skill `email-outreach-client` must not hide it.
- **Ordering mailboxes** costs **around $13/domain/year** plus **around
  $4.50/mailbox/month**. `email-outreach-mailboxes` must always state the exact
  price quoted by the API and get the customer's confirmation before placing
  the order — never place it silently.

Never place an order, or create a client that may purchase a seat, without the
customer having been told the cost in plain terms first.

## Calling the AdvisorReach API

All three child skills call `{ADVISORREACH_API_URL}/smartlead/v1/...` with
`Authorization: Bearer {ADVISORREACH_API_KEY}`.

**Allow at least 300 seconds for a response** (`curl --max-time 300`, or the
equivalent read timeout in whatever HTTP client you use). Creating a client is
slow because it provisions upstream — cutting the request off early does not
mean it failed, it means you stopped waiting.

## The retry contract — read this before any child skill retries anything

If a call to **create a client** returns **504**, that is *not* a failure — the
client may already have been created upstream and the response simply didn't
come back in time. **Re-issue the identical request once, with the exact same
email address.** The email address is the idempotency key on the far side: the
same email converges on the same client and will not create a duplicate or
spend money twice. Never change the email between the original attempt and the
retry, and never retry more than once — if the second attempt also times out or
fails, stop and tell the customer honestly rather than looping.

This contract applies specifically to the create-client call. It does not make
mailbox ordering safe to retry — see `email-outreach-mailboxes` for why that one
is different.

## Rules

- Never claim any part of this is done before the API confirms it — a 200
  response for one step is not evidence the next step happened.
- Never expose internal ids (client ids, order ids, database ids) to the
  customer — only names, domains, addresses, and money amounts they gave you or
  that are meaningful to them.
- A 404 from any of these endpoints means "not found or not yours" — never
  treat it as a permissions error to work around; it means the thing does not
  exist for this customer, full stop.
- If anything is unclear about a customer's intent (which domain, how many
  mailboxes, which client if they have more than one), ask — do not guess and
  proceed, especially where money is involved.