MisarMail

View saved version →

---
name: ab-test-campaign
description: Design and run an A/B test on a MisarMail campaign — subject line, content, sender name, or send time. Use for "A/B test", "split test", "which subject works better", or testing email variants.
---

# A/B test a campaign

## Check the audience is big enough — first

Call `get_campaign` (or `list_campaigns`) for the recipient count.

With the default 20% sample split across two variants, an audience of 10,000
gives ~1,000 per variant. Below that, normal variance swamps the effect and the
"winner" is noise. **Say so plainly and recommend against testing** rather than
running a test that produces a confident-looking but meaningless result.

## Design

`create_ab_test` takes `campaign_id`, a `type`, and 2–5 `variants`:

| Type | Varies | Notes |
|---|---|---|
| `subject` | Subject line | Highest signal, easiest to interpret |
| `content` | Body HTML | Test one change, not a redesign |
| `from_name` | Sender name | Often larger effect than expected |
| `send_time` | Delivery time | Needs a longer measurement window |

For subject tests, `generate_subject_lines` produces candidates. Test variants
that differ in *approach* (question vs. statement, specific vs. curiosity), not
in wording trivia — two near-identical subjects cannot produce a real winner.

Set `winner_metric` to match the goal: `open_rate` for subject tests,
`click_rate` or `conversion_rate` for content.

## Selecting the winner

`select_ab_test_winner` **sends the winning variant to the entire remaining
audience**. It is irreversible. Do not call it until results are in, and never
without explicit confirmation.

Let the sample run at least 4 hours — opens arrive over hours, and an early
reading systematically favours whichever variant reached the more active
segment first.

View saved version →

---
name: audit-deliverability
description: Diagnose why MisarMail emails land in spam or bounce, and produce a prioritized fix list. Use for "emails going to spam", "not being delivered", "low open rate", "domain reputation", DMARC/SPF/DKIM, or blocklist questions.
---

# Audit deliverability

## Gather everything before concluding

Run all four — a partial picture produces the wrong recommendation:

| Tool | What it tells you |
|---|---|
| `get_deliverability_score` | Headline score 0–100 and grade, with contributing factors |
| `run_deliverability_audit` | Detailed findings across auth, reputation, content, blocklists |
| `check_dmarc` (per domain from `list_domains`) | Live SPF/DKIM/DMARC records and alignment failures |
| `get_warmup_status` | Whether volume is exceeding warm-up capacity |

Also call `list_contacts` with `status=bounced` and `status=complained` — a
dirty list depresses deliverability no matter how good the DNS is.

## Report

Group findings by impact (high / medium / low). Every item must name the
**specific** record, setting, or segment to change. "Improve your SPF record"
is not actionable; "add `include:_spf.misar.io` to the TXT record on
example.com, which currently reads `v=spf1 -all`" is.

## Common causes, in the order they actually occur

1. **Missing or misaligned DMARC/SPF/DKIM** — by far the most frequent. A
   `From:` domain that does not align with the signing domain fails
   authentication at Gmail and Outlook regardless of content.
2. **Sending above warm-up capacity** on a new domain or IP.
3. **List hygiene** — mailing bounced or long-unengaged addresses. See the
   `clean-contact-list` skill.
4. **Content signals** — link shorteners, image-only bodies, missing text part.

## Do not

- Recommend changes to a domain you have not called `check_dmarc` on.
- Report a score without saying what is dragging it down.

View saved version →

---
name: build-email-automation
description: Design and build a MisarMail automation workflow — welcome series, drip sequence, re-engagement, or onboarding. Use for "automate", "drip", "welcome series", "sequence", or trigger-based email.
---

# Build an email automation

## 1. Check what already exists

`list_automations` first. Two automations on the same trigger will both fire,
and the contact receives duplicate mail — a failure users usually discover from
a complaint rather than from the dashboard.

## 2. Design before building

Choose a trigger: `contact_created`, `tag_added`, `campaign_opened`,
`link_clicked`, or `date_based`. Then lay out the steps with explicit delays
and explain each choice to the user.

Practical guidance worth stating:
- First email within an hour of the trigger; the rest spaced 2–4 days.
- Keep a welcome series to 3–5 emails. Longer sequences bleed unsubscribes.
- Include an exit condition (a tag applied on conversion) so a converted
  contact stops receiving the sequence.

## 3. Build it inactive

`create_automation` with `active: false`. Show the result via `get_automation`
and let the user read the steps back before anything can fire.

Only call `toggle_automation` with `active: true` after explicit confirmation.
Activating starts enrolling live contacts immediately.

## Templates

`list_templates` and `create_template` — use `{{variable}}` placeholders and
preview substitution with `render_template` before wiring a template into a
step. An automation that ships `Hi {{first_name}}` to contacts with no first
name is a visible, embarrassing failure.

View saved version →

---
name: clean-contact-list
description: Audit and clean a MisarMail contact list — bounced, complained, and unengaged contacts. Use for list hygiene, re-engagement, suppression, or "why is my open rate falling".
---

# Clean a contact list

## Assess

- `list_contacts` with `status=bounced` and `status=complained` — these must
  never be mailed again. Continuing to send to them is what turns a reputation
  problem into a blocklisting.
- `get_contact_score` with no `contact_id` returns the lowest-engagement
  contacts.
- `get_analytics` for the open-rate trend over time.

Report what share of the list each category represents. Percentages, not raw
counts alone — "412 bounced" means nothing without the list size.

## Recommend, then ask

Propose which segments to suppress and which to try re-engaging first. A
re-engagement campaign to genuinely unengaged contacts is usually worth one
attempt before suppression; contacts who complained are not.

**Never call `update_contact` to unsubscribe anyone without explicit
per-segment approval.** Unsubscribing is effectively irreversible from the
user's perspective and they may be reacting to a number they misread.

## Importing

When importing, `import_contacts` handles up to 5,000 per call and updates
rather than duplicates existing addresses. Before a large import, confirm the
contacts opted in — mailing a purchased or scraped list breaches CAN-SPAM and
GDPR and will damage the sending domain for every other campaign.

Spot-check a sample with `validate_email` first and report the rejected rows.

View saved version →

---
name: email-performance-report
description: Produce a MisarMail performance report — opens, clicks, deliverability, revenue attribution. Use for "how are my emails doing", weekly/monthly reports, or campaign performance analysis.
---

# Email performance report

## Gather

- `get_analytics` — sends, delivers, opens, clicks, bounces, complaints
- `list_campaigns` with `status=sent` — per-campaign comparison
- `get_deliverability_score` — reputation context for the numbers
- `get_revenue_attribution` — revenue attributed to email
- `generate_report` — `campaign_performance`, `engagement_funnel`,
  `cohort_analysis`, or `send_time_heatmap`

## Interpret, do not just report

Every metric needs a reference point:

| Metric | Healthy | Read as |
|---|---|---|
| Open rate | 20–25% | Subject line + sender reputation |
| Click rate | 2–5% | Content relevance and offer |
| Bounce rate | under 2% | List quality; above 5% is urgent |
| Complaint rate | under 0.1% | Consent and expectation-setting |

Apple Mail Privacy Protection inflates open rates by auto-fetching images.
Treat open rate as directional and lean on clicks for anything that matters.

## Structure

Headline metrics; best and worst campaign each with a one-line reason;
deliverability status; revenue; then the single highest-impact action for the
next period.

Keep it under 400 words. If a figure was unavailable, say so — never estimate
a number and present it as measured.

View saved version →

---
name: run-email-campaign
description: Create, review, and send a bulk email campaign in MisarMail. Use when the user wants to email a list, newsletter, segment, or announcement to many recipients.
---

# Run an email campaign

A campaign sends real email to many people and cannot be recalled. Treat every
step as requiring confirmation.

## 1. Check capacity first

Call `get_warmup_status`. Sending above warm-up capacity on a young domain is
the fastest route to throttling or a blocklist. If the audience exceeds the
remaining daily capacity, say so and offer to split the send across days.

Call `get_deliverability_score` too — sending a large campaign from an account
already scoring poorly compounds the damage.

## 2. Build it

- `list_templates` / `render_template` to reuse existing design, or supply
  inline `html`.
- `create_campaign` creates a **draft**. It never sends.
- Confirm the audience with `get_campaign` and report the recipient count back
  to the user in plain numbers before going further.

## 3. Send

- `send_campaign` sends immediately.
- `send_campaign` with `scheduled_at` schedules it.

Get explicit confirmation of the recipient count and the subject line first.

## 4. Report

After sending, `get_analytics` with the campaign id. Useful reference points:
open 20–25%, click 2–5%, bounce under 2%, complaints under 0.1%. Flag anything
outside those ranges rather than reporting the number without context.

## Testing

Suggest an A/B test on the subject line when the audience is large enough —
see the `ab-test-campaign` skill. Below roughly 1,000 recipients per variant a
test will not produce a trustworthy winner; say so instead of running one.

View saved version →

---
name: send-transactional-email
description: Send a one-off or transactional email through MisarMail. Use when the user asks to send, draft-and-send, or reply to an email — including receipts, notifications, welcome messages, and personal outreach.
---

# Send a transactional email

## Before sending

1. **Resolve a verified sender.** Call `list_domains`. `from.email` must belong
   to a verified domain — an unverified sender is the single most common send
   failure, and the API rejects it outright.
2. **Validate unfamiliar recipients.** Call `validate_email` for addresses the
   user typed by hand. Bounces damage sender reputation far more than the one
   email is worth.
3. **Show the draft and wait.** Present subject and body, and get explicit
   confirmation. Sending is irreversible.

## Sending

Call `send_email` with `from`, `to`, `subject`, and `html` (plus `text` as a
fallback — some clients and filters penalise HTML-only mail).

Pass `idempotency_key` whenever a retry is plausible: without it a network
timeout that actually succeeded will deliver the message twice.

## Testing without delivering

If the user is iterating on wording or a template, suggest sandbox mode: sends
are captured instead of delivered, and `list_sandbox_sends` shows exactly what
would have gone out. `clear_sandbox` resets it.

## Do not

- Send to a list you assembled from `list_contacts` — that is a campaign. Use
  `create_campaign` + `send_campaign`, which applies unsubscribe handling and
  rate limiting that `send_email` does not.
- Invent a sender address. If no verified domain exists, say so and point the
  user at `add_domain`.

View saved version →

---
name: setup-sending-domain
description: Add and verify a custom sending domain in MisarMail, including SPF, DKIM, DMARC, and inbound routing. Use for "send from my own domain", DNS setup, domain verification, or inbound email.
---

# Set up a sending domain

## 1. Add it

`add_domain` returns the DNS records to publish. Give the user the exact record
type, host, and value — a paraphrase produces a broken record.

## 2. Wait, then verify

`verify_domain` re-checks DNS. Propagation takes minutes to 48 hours, so a
failure right after publishing is expected rather than an error. Say that
instead of letting the user think something is wrong.

`check_dmarc` shows what is actually resolving publicly, which is the fastest
way to spot a record pasted into the wrong host (a very common mistake:
`_dmarc.example.com` published as `_dmarc.example.com.example.com`).

## 3. Warm up before volume

`get_warmup_status` — a new domain has no reputation. Ramping gradually is what
separates a domain that lands in the inbox from one that lands in spam
permanently. Do not let a user send a large first campaign from a brand-new
domain without flagging the risk.

## DMARC policy

Start at `p=none` (monitor only), then move to `quarantine` and finally
`reject` once `check_dmarc` shows SPF and DKIM aligned and passing. Jumping
straight to `p=reject` before alignment is confirmed silently blackholes
legitimate mail.

## Inbound

`configure_inbound_domain` routes replies into the unified inbox and returns
the MX record to publish. Use a subdomain (`reply.example.com`) so it cannot
interfere with the organisation's primary mail.