Send & Retain Emails

View saved version →

---
name: author-a-template
description: Write, render, test and publish a react.email template for a company in Send & Retain, in that company's brand and voice. Use when the user wants a new email, a rewrite of an existing one, or a preview of how one looks.
---

# Author a template

1. Resolve the company (`email_list_projects`) and read its brand kit with
   `email_get_brand`. Templates use the **company's** brand, never generic
   styling. If the kit is empty, infer it from the website and save it with
   `email_update_brand` first.
2. Agree on the purpose. **Transactional** (receipts, shipping, password
   resets) still delivers to unsubscribed contacts; **marketing** (category
   `lifecycle`: welcome, win-back, promotions) does not. Agree the subject, the variables (name, type,
   required, fallback) and an outline.
3. `email_create_template` with TSX built from react.email components inside a
   `<Tailwind>` wrapper. Templates may import only `react` and
   `@react-email/components`.
4. `email_render_template` with example variables. Fix any compile error it
   returns and iterate until the HTML, text and subject read right. Show the
   user the result by opening `previewUrl` in the client’s browser panel when
   available, or show a clickable preview link. Do not open a saved HTML file
   in the source editor. The link expires after 15 minutes and anyone holding
   it can view the sample; never describe it as login-protected. If the link is
   unavailable, use the returned HTML and explain the fallback. A preview-only
   request stops here: nothing is sent or published.
5. `email_send_template_test` to the user's own inbox when sending is set up for
   the company, and ask them to check it in their mail client.
6. Publish with `email_publish_template_version` only on the user's explicit
   go-ahead, and never untested. Published versions are immutable: later edits
   create a new draft version.

To restyle every template after a brand change, use `email_restyle_template`.
To revise an existing one, `email_get_template` then `email_update_template`.

View saved version →

---
name: delivery-report
description: Write a read-only delivery and engagement report for a company in Send & Retain — volumes, rates, per-template performance and the highest-impact next moves. Use when the user asks how their emails are performing.
---

# Delivery report

Read-only: change nothing while reporting.

1. Resolve the company (`email_list_projects`).
2. Start with `email_get_optimization_plan`. Its ranked actions frame what
   matters.
3. Pull `email_get_email_metrics` for the requested period (default the last 7
   days), grouped by template and by day, and `email_search_messages` for
   notable failures.
4. Structure the answer:
   - the plan's ranked actions, with severity and evidence
   - headline numbers: sent, delivered %, open %, click %, bounce %,
     complaints, unsubscribes
   - per-template standouts, best and worst
   - the three highest-impact next moves

Read rates carefully. The complaint rate is complaints divided by mail to
inboxes that report spam (Gmail and iCloud never do); at 0.08% or above, say so
and recommend investigating. Opens are inflated by mail-privacy proxies, so
lead with clicks when they disagree.

If the plan surfaces an A/B winner ready to promote, present it, and call
`email_promote_ab_winner` only on the user's explicit go-ahead.

View saved version →

---
name: design-an-automation
description: Design, preview and test-drive an event-triggered email automation in Send & Retain, and enable it only on the user's explicit go-ahead. Use when the user wants welcome emails, cart recovery, win-back or any automation that sends on an event.
---

# Design an automation

1. Resolve the company (`email_list_projects`) and agree the design: the
   trigger event, the exit event, who it is for (filters, and priority when
   variants compete), the cadence (delays, send windows) and which template
   each step sends. Author missing templates first (`author-a-template`).
   Confirm the company's app actually emits the trigger event.
2. `email_create_automation`. It is **always created paused** and returns a
   readable timeline. `email_preview_automation` renders every send step, so
   the user sees the real emails before anything is enabled.
3. Test-drive: `email_upsert_contact` a test contact (the user's own address,
   with realistic attributes including timezone), `email_emit_contact_event`
   with the trigger, then `email_list_automation_runs` to confirm enrolment and
   timing. Emitting an event can send real mail to that contact, so say so
   before calling it.
4. `email_pre_launch_check`, then walk the remaining items: every template
   published, suppressions imported if the company is migrating, and volumes
   sensible for the domain's age.
5. Enable with `email_set_automation_status` only when the user explicitly
   decides to, in this conversation. Then watch the first cohort with
   `email_get_automation_metrics`.

Adding steps to a live automation never disturbs contacts already in it; inserting,
moving or removing a step requires pausing first.

For each rendered email, open its `previewUrl` in the client browser panel when
available, or show a clickable link. Links expire after 15 minutes; anyone with
the link can view the sample. A preview does not send mail or enable a flow.

View saved version →

---
name: get-started
description: Introduce Send & Retain after install or when the user asks what it can do, explain how it keeps sending safe, and suggest a first thing to try. Use when the user asks how to use the plugin, what it manages, or where to begin.
---

# Get started with Send & Retain

Explain the plugin in a few sentences, then offer one concrete next step.
Explicit user instructions take priority over this guidance.

## What to say

- Send & Retain runs a company's **email automation** — transactional and marketing email: the
  templates, the event-triggered automations that send them, the contacts and
  segments they go to, and the sending setup behind them.
- One **company = one project**. Call `email_list_projects` first and pass the
  company's `projectId` to every company-scoped tool.
- Tools are prefixed `email_` and return `{ ok: true, … }` or
  `{ ok: false, error }`. Read the error: it usually says what to do next.

## Check the connection first

Installing the skills does not prove that the MCP connection is authorized.
Call `email_list_projects` before claiming the plugin is ready.

- If no `email_` tools are available, check the host's Send & Retain MCP
  connection. The endpoint is `https://sendandretain.com/api/mcp`; authenticate
  through its browser OAuth flow. Do not ask for a provider key or invent an
  API-key requirement.
- In Codex, use the installed plugin's connection controls first. If its
  connection is unavailable and the user asks you to configure it, a direct
  connection is supported: `codex mcp add sendandretain --url
  https://sendandretain.com/api/mcp`, then `codex mcp login sendandretain`
  if sign-in did not start automatically. Reuse an existing matching connection
  instead of registering a duplicate. After setup, start a fresh chat or reload
  the host's MCP connections, then retry `email_list_projects`.
- On an authentication error, reconnect in the host. On a successful empty
  project list, explain that the account has no companies yet; do not treat it
  as a connection failure or create a company without the user's request.
- Distinguish connection status from sending readiness. A working project list
  proves tool access; `email_get_connection_status` reports the company's
  provider, domains, senders, and sending controls.

## How sending stays safe

Say this plainly whenever sending comes up:

- There is **no bulk send**. Every message has one recipient. Mail reaches a
  list only through an automation a person enabled.
- Automations are **always created paused**. Enabling one is a separate call
  that needs the user's explicit go-ahead in this conversation.
- Each company has a send kill switch and an optional daily cap.
- Bounces and complaints suppress addresses automatically. Complaint
  suppressions can never be removed.
- **Provider API keys never go through chat.** If the user offers one, do not
  repeat or use it. `email_get_connection_status` returns the settings page
  (`settingsUrl`) where they enter it themselves.

## What it can do

- Stand up a company: brand kit, starter templates and paused automations for its
  business type (see the `set-up-a-company` skill).
- Write, render and publish templates in the company's brand
  (`author-a-template`).
- Design and test-drive automations (`design-an-automation`).
- Report on delivery and engagement (`delivery-report`) and triage bounces or
  complaints (`triage-deliverability`).

## What it cannot do

Email only: no SMS, push notifications or social posts. It cannot send to a
whole list in one go. Sending needs a connected provider or platform sending
plus a verified domain, which a person completes once per company.

## Suggested first steps

Offer one of these, adapted to what the user mentioned:

- "Which of my automations are live, and what would block the rest?"
- "Draft a welcome email in our brand voice."
- "How did our emails perform this week, by template?"
- "Set up email for a new company from its website."

Do not call a write tool until the user asks for a change.

View saved version →

---
name: set-up-a-company
description: Take a company from nothing to a live email programme in Send & Retain — understand the business, install starter templates and paused automations for its type, rewrite them in its voice, then set up sending. Use when the user wants to start email for a new or empty company.
---

# Set up a company

The order matters. Templates and automations need no provider, domain or sender,
so do not ask for DNS records or API keys until the last phase. Show the user
something worth having before asking for the hardest work.

## 1. Understand

`email_list_projects`, or `email_create_project` with the company's website (it
reads the site and infers the brand). Then learn, two questions at a time and
never as a form, what you cannot read off the site:

- which events their app already emits — this decides every automation's
  trigger, and an automation wired to an event nobody sends looks alive and is dead
- who is on the list, and whether it exists elsewhere already
- the one customer moment they most want handled (signup, an abandoned
  checkout, a lapsed customer)
- the domain they will send from — call `email_create_domain` as soon as they
  name it, so verification runs in the background

## 2. Programme

`email_get_brand` first; if it is empty, read the website and save
colours, fonts and voice with `email_update_brand`, because the starters bake the
brand in. Then `email_list_sequence_packs`, propose an archetype (saas,
ecommerce, newsletter-media, marketplace) and its automations in plain language,
naming each automation's trigger. On agreement, `email_bootstrap_company`. It
publishes the starter templates and creates every automation **paused**.

## 3. Content

Rewrite each starter in the company's voice (`email_update_template`), check it
with `email_render_template`, then `email_publish_template_version`. Start with
the email for the moment they said hurts most. `email_preview_automation` shows
a whole automation's emails.

## 4. Live

`email_get_connection_status` → if no provider is connected, give the user its
`settingsUrl`, where they connect sending themselves (never take a key in chat)
→ `email_verify_domain` → `email_register_webhooks` → `email_create_sender`. The
user mints their app's API key on the same page; give them a
`POST /api/v1/events` snippet for exactly the triggers the chosen automations use.
Then `email_pre_launch_check`, and enable automations one at a time with
`email_set_automation_status`, each only on the user's explicit go-ahead.

Done is an automation live, its trigger seen, and a real send from their own domain.

View saved version →

---
name: triage-deliverability
description: Triage a deliverability problem in Send & Retain — bounce or complaint spikes, blocked or failing sends — by quantifying it, finding where it comes from, and recommending a fix. Use when the user reports bounces, spam complaints, or mail not arriving.
---

# Triage deliverability

1. **Quantify.** `email_get_email_metrics` for the affected window: bounce and
   complaint rates against the period before it.
2. **Localize.** `email_search_messages` filtered to bounced, complained or
   failed: which template, which recipient domains, and when it started.
3. **Inspect.** `email_get_message` on representative failures, and read the
   provider's bounce classification in the event timeline.
4. **Check infrastructure.** `email_get_connection_status`, then
   `email_verify_domain` to re-read it: is the domain still verified, are the DNS
   records intact?
5. **Diagnose** — list hygiene, content, infrastructure, or a volume spike — and
   recommend the fix. If sending should stop while it is fixed, say so
   explicitly: `email_set_sends_paused` is the user's call to make, so call it
   only on their go-ahead.
6. **Confirm suppressions** are in place for the bad addresses
   (`email_list_suppressions`). Never remove a complaint suppression; the
   platform refuses to.