Email Report

Email Report

The 3-hour tax every email marketer pays: pulling last period's numbers, charting the trend, explaining the variance, and writing commentary in the right voice for the audience. This skill does it in one command and outputs three versions — Slack ping, CEO email, board deck section — so you can ship the one your stakeholder needs.

Requires: Cogny MCP + a connected ESP. Sign up

Usage

/email-report — monthly report, all three formats (default) /email-report weekly — last 7 days /email-report monthly ceo — monthly, only the CEO email /email-report weekly slack — weekly, only the Slack update

Step 0: Is Cogny connected?

If no mcp__cogny__* tools exist (no list_integrations, no cogny_status), print this and stop:

Copy code
Email Report needs your marketing data through Cogny's MCP gateway.

1. Sign up at https://cogny.com and connect your ESP (Klaviyo, Mailchimp, Rule, Get a Newsletter, Brevo, MailerLite, Drip, Salesforce Marketing Cloud, Symplify or Braze); a store, Stripe or GA4 adds revenue context.
2. Add Cogny to .mcp.json in your project:
   {"mcpServers": {"cogny": {"type": "http", "url": "https://app.cogny.com/mcp"}}}
3. Restart Claude Code; it opens a browser for the OAuth login on first use.

Nothing to run without Cogny.

When Cogny is connected but no ESP is, say "connect your ESP in Cogny" and stop; a connected integration that fails its health check gets "reconnect in Cogny".

Prerequisites Check

Detect connected ESP (on Cloud, mcp__cogny__list_integrations; name any unhealthy integration as broken). If none, stop and prompt. Also note which store (Shopify, WooCommerce, Abicart, Litium), billing source (Stripe, for SaaS) and web analytics (GA4, Plausible) are connected — they supply revenue and email-driven sessions.

Health check: health_status misses revoked tokens, so make one cheap read per integration before relying on it (e.g. Mailchimp tool_get_account_info, Get a Newsletter tool_list_senders, Klaviyo get_account, GA4 tool_run_report for one day, Stripe stripe_api_read GetSubscriptions with limit: 1). A 401, Forbidden or scope error means 🔴 "reconnect in Cogny": name it, don't retry, and report from the rest.

Missing tool: if a tool named here isn't exposed by the workspace, call mcp__cogny__refresh_mcp_discovery once, use the fallback named next to the tool for this run, mark that source ⚠ "needs reconnect", and tell the user to reconnect the Cogny MCP. Never loop on refresh. Get a Newsletter fallbacks: tool_get_report_have_not_opened → that report's list contacts minus the openers from tool_get_report_opens; tool_get_report_link_clicks → tool_get_report_opens (per-contact click counts) or tool_get_report_clicks (per-link totals); tool_get_report_opens_aggregated → the totals in tool_get_report. Mailchimp tool_get_campaign_content → tool_get_campaign for the headers, and ask the user for the body.

ESP connected but 0 sends in the window: skip that ESP's campaign section with a one-line note ("Rule: connected, 0 sends in ") and keep its list-size numbers. If no ESP sent anything in the period, see "Zero sends in the period" in step 2.

Works with

Revenue from the store and analytics (enhanced when connected):

Report ESP-attributed revenue, GA4 email revenue and store (or Stripe) revenue as separate labeled lines. They use different attribution windows and never add up.

Steps

1. Define the period and read the previous report

State the exact date ranges up front.

Call read_context_node with path: "insights/email/reports/<weekly|monthly>/latest". If it exists, it holds the previous report's narrative and key numbers: use them in "What happened" ("this matches the trend from last month" / "this reverses the dip we flagged"). If it doesn't exist, this is the first run for that mode; say so.

2. Pull the data

Per-ESP tool adapter. The right tool depends on which ESP is connected:

Get a Newsletter: tool_list_sent rows carry subject, send time and report_id, so tool_get_sent isn't needed. Its delivered equals sent_to even when mails bounced, so use sent_to − bounced as the delivered denominator. Exclude test sends (under 10 recipients, or "test" in the subject).

For Brevo, MailerLite, Drip, Salesforce Marketing Cloud, Symplify and Braze, use the tools in Works with above. Pull each ESP's numbers separately; if several are connected, the report gets one metrics column per ESP, never a blended total.

For the current window AND the comparison window, pull:

Campaign broadcasts:

• Each campaign's subject, send date, recipient count, opens, unique opens, clicks, unique clicks, unsubs, bounces.
• Revenue attributed — Klaviyo, Braze, Symplify. For Klaviyo, fetch "Placed Order" events scoped to the send window and attribute by campaign (or get_campaign_values_report with revenue_per_recipient). Braze returns revenue in braze_get_campaign_analytics; Symplify returns conversion amount per delivery. For the other ESPs, omit ESP-attributed revenue and use GA4/Plausible email-driven revenue or conversions if connected, labeled as such.

Flows / automations — varies by ESP:

• Klaviyo: flow name, triggered volume, revenue per flow (via events).
• Mailchimp: automation name, sends, opens, clicks (no revenue).
• Rule: journey name + limited metrics.
• Drip: workflow names from list_workflows; Email Series subscriber counts from get_campaign.
• Salesforce Marketing Cloud: get_journey_email_performance — lifetime numbers, so show them as "since launch", never as this period's change.
• Symplify: list_journeys gives names only; journey performance isn't exposed.
• Braze: Canvas name + braze_get_canvas_summary for the window (revenue included).
• Brevo, MailerLite: automations aren't exposed; skip and say so.
• Get a Newsletter: no flow object exists. Skip this section; use a "recurring sends" proxy if the user has a newsletter cadence.

List-level metrics:

• List size at period start vs end
• New subscribers in period
• Unsubscribes in period
• Net change + growth rate

Zero sends in the period: if no connected ESP sent a broadcast in the current window, don't compute rates (they'd be 0/0). Output a short report instead: "No email sends in (last send: , )", the list-size change, any flow/journey numbers that exist, and the store/Stripe/GA4 context lines. Flag the gap as a finding if the previous report showed a regular cadence.

Unconnected senders (GA4): compare the GA4 email sessionCampaignName values with the connected ESPs' sends in the window. A campaign with email sessions that matches no ESP send means email is going out from a sender Cogny can't see (another ESP, a CRM, a product mailer). List those campaigns with their sessions and say "sent from an unconnected tool; connect it to include it in the report".

3. Compute the report metrics

For each window, compute:

Show absolute value + % change vs prior period + % change vs rolling baseline.

4. Identify movers

Rank campaigns in the current window by open rate, CTR, and revenue. Identify:

• Top performer — best campaign by revenue (or by CTOR if no revenue data)
• Worst performer — bottom by revenue/CTOR
• Anomaly — campaign whose metrics are >2σ from the user's typical baseline (surprise hit or surprise flop)

For each, write a one-sentence "why" hypothesis based on visible attributes (subject style, send time, segment, content type).

5. Explain variance

Don't just say "CTR dropped 8%." Explain it. Cross-reference:

• Did send volume change? More sends to less-engaged segments drag rate metrics even if absolute revenue is fine.
• Did the segment mix change? (All-list sends vs engaged-only)
• Did cadence change? (More sends per week → fatigue)
• Did a specific campaign drag the average? (One dud to a huge segment)
• Did list hygiene change? (Big unsub event or re-engagement deadline)
• Was there an external event? (holiday, launch, outage)

Phrase findings as claim → evidence:

"Open rate dropped from 28% to 22%. Two of four sends this month went to the dormant 180-day segment (120k recipients at 14% open), which pulled the average down. If you look at engaged-segment sends only, open rate actually rose from 34% to 36%."

6. Generate the three outputs

6.1 Slack update (≤500 chars, 3 bullets)

Copy code
📧 Email – <period label>
• Sends: <N> ( <±>% vs prior)  |  Open: <X>% ( <±>pp)  |  CTR: <Y>% ( <±>pp)
• 🏆 Top: "<subject>" — <metric>  |  ⚠️ Watch: <one-line variance call>
• Revenue: $<X> ( <±>% vs prior)  |  List: <±>% net growth  |  Next week: <1-line plan>

6.2 CEO email (≤250 words, narrative)

Copy code
Subject: Email performance — <period label>

Hi <CEO first name>,

Quick update on email this <period>:

Headline: <one-sentence summary — is it good, bad, or mixed?>

What happened:
[2-3 sentences explaining volume, rate-metric movement, revenue. Tie to a
business narrative — launches, campaigns, segment focus.]

What's notable:
[1-2 sentences. Top campaign or surprise win or flagged concern.]

What's next:
[1-2 sentences. Concrete plan for next period. Pick ONE action, not five.]

Happy to dig deeper on any of this.

<signoff>

6.3 Deck section (full)

Copy code
EMAIL PERFORMANCE — <period label>

Summary
  <two-sentence narrative>

Key metrics
  [table: current / prior / rolling / %Δ]
  Sends, Open rate, CTR, CTOR, Unsub rate, Revenue per send, List size

Trend
  [describe what a chart should show — up-and-to-the-right, step change, etc.]

Campaign roundup
  🏆 Best:  "<subject>"
           <segment>, <recipients>, <metric wins>
  📉 Worst: "<subject>"
           <what happened>

Flow performance (if applicable)
  [table of top 3 flows by revenue, with recipient count and conv rate]

What moved the needle
  [2-3 bullets — claim → evidence]

Plan for next <period>
  [2-3 bullets — concrete, owned, measurable]

7. Save the narrative

Persist the period summary to Cogny's context tree so future /email-report runs have historical continuity:

jsonCopy code
{
  "path": "insights/email/reports/<weekly|monthly>/latest",
  "body": "<period dates + the narrative summary + key numbers per ESP>"
}

Overwrite latest (step 1 reads it next run) and also write the same body to insights/email/reports/<weekly|monthly>/<YYYY-MM-DD> as the dated archive.

8. Create findings for notable issues

For anything serious (unsub rate spike, deliverability drop, revenue collapse, an unconnected sender), record it so it lands in the dashboard — not just the report. On Cloud call create_ticket first (fields mapped per section 2 of the routing guide); on Solo call create_finding:

jsonCopy code
{
  "title": "Unsub rate doubled vs prior month (0.18% → 0.37%)",
  "body": "<which campaigns drove it, which segment, recommended fix>",
  "action_type": "list_hygiene",
  "priority": "high"
}

Output defaults

• If the user didn't specify a format, output all three and label them clearly.
• Lead with the Slack version — fastest to read if they're skimming.
• Include the raw metric table at the end so the user can copy numbers out.

Notes

• Open rate is noisy since Apple MPP. Always report CTR and CTOR alongside. If open rate moves >5pp but CTOR doesn't, it's probably MPP population change, not real behavior.
• For first-ever run, there's no prior period to compare to — call this out explicitly and use absolute numbers only.
• Don't invent revenue numbers. ESP-attributed revenue exists only for Klaviyo ("Placed Order" events with a value field), Braze and Symplify. For Mailchimp, Rule, Get a Newsletter, Brevo, MailerLite, Drip and SFMC, say "revenue not exposed by this ESP's MCP" and use GA4/Plausible email-driven revenue, store or Stripe totals for context, or user-pasted revenue — each labeled with its source.
• Definitions differ per ESP. Klaviyo, Mailchimp and Brevo opens include Apple MPP machine opens unless the payload separates them; Get a Newsletter reports per sent mail; SFMC journey totals are lifetime. Name the ESP on every number and never average rates across ESPs.

Recording findings

Use create_ticket when the workspace has it (Cloud) and create_finding otherwise (Solo). The fields differ; see section 2 of ../marketing-engineer/references/mcp-routing.md.