Mailgo Campaign Suite

One skill, complete cold email pipeline. From recipient verification to campaign reporting — everything runs through bundled scripts with zero third-party dependencies.

Step 0 — Authentication Setup

Required: MAILGO_API_KEY environment variable must be set before any other step.

Quick check

# Confirm the variable is set (shows first 5 characters only)
echo "${MAILGO_API_KEY:0:5}"

If output is non-empty → proceed to Step 1. If empty → follow the setup flow below.

Setup Flow

Sub-step 0.1 — Register or Log In

New users:

1. Go to https://app.mailgo.ai
2. Click "Sign Up" and complete registration

Existing users:

1. Go to https://app.mailgo.ai
2. Log in with your credentials

Sub-step 0.2 — Create Personal Token

Once logged in:

1. Click your avatar in the bottom-left corner
2. Select Personal Tokens from the menu
3. Click Create Token
4. Give your token a descriptive name (e.g., "Claude Code")
5. Copy the generated token

SECURITY: Never paste the token into chat. It must only be set as a local environment variable.

Sub-step 0.3 — Set Environment Variable

# macOS / Linux (permanent)
echo 'export MAILGO_API_KEY="YOUR_TOKEN"' >> ~/.zshrc && source ~/.zshrc

# Windows PowerShell (permanent)
[System.Environment]::SetEnvironmentVariable('MAILGO_API_KEY', 'YOUR_TOKEN', 'User')

Replace YOUR_TOKEN with the copied value.

Sub-step 0.4 — Verify

# macOS / Linux — shows first 5 characters to confirm without exposing the token
echo "${MAILGO_API_KEY:0:5}"

# Windows PowerShell
$k = $env:MAILGO_API_KEY; if ($k) { $k.Substring(0, [Math]::Min(5, $k.Length)) } else { "" }

If output is non-empty, you're ready. If empty, run source ~/.zshrc or open a new terminal.

Key Facts

Auth Error Handling

Step 0.5 — Upfront Information Gathering

Collect all required information in a single interaction before starting the pipeline.

Ask all questions at once. Do not ask in separate rounds. The user fills in what they know; mark anything skipped as "not provided".

When to run: Only when the user intends to create a new campaign. Skip for report/manage/replies tasks.

Group A — Your Information (for email signature & credibility)

Ask all of these together in one message:

Group B — Your Recipients

Ask all of these together in the same message as Group A:

If the user provides a file, auto-detect columns after reading the file headers — then mark fields 9–12 automatically without asking again.

⚠ Header Warning: Column detection relies entirely on header names. Files without headers (e.g. a bare two-column XLSX with email + company but no row of column names) will only have col_0, col_1, … as synthetic headers — none of which match any known field name. As a result, only the email column can be identified by content scanning; all other columns (company, name, title, domain) will be silently discarded. Whenever a user provides a headerless file and you can see that extra columns exist (e.g. "two-column spreadsheet"), proactively warn them: "Your file appears to have no header row. Only email addresses were imported — company names and other fields were not recognized. Add a header row (e.g. email, company, name) and re-upload to include that data."

Auto-Derive Name from Email Prefix (CRITICAL)

Immediately after receiving the recipient list, check whether name data is available. If has_name is false (no name column detected, no names provided inline):

1. Extract name from each email's local-part (the portion before @):
   • Split on ., -, _ → capitalize each segment → join with space
   • Examples: alice.smith@co.com → "Alice Smith", john_doe@co.com → "John Doe", jdoe@co.com → "Jdoe"
2. Store the derived name into each recipient entry in session_context.recipients
3. Set recipient_fields.name = true with source noted as "auto-derived from email prefix"
4. Do this silently — do not ask the user, do not announce it; just note it in the Step 3 change summary

This ensures #{Name} is always available as long as there are valid email addresses.

Handling Partial Answers

Carry Forward

Store all answers as session context. Every subsequent step uses this context directly — never ask for the same information again.

session_context = {
  sender_company:   "...",   # or null
  sender_name:      "...",   # or null
  sender_title:     "...",   # or null
  sender_website:   "...",   # or null
  sender_offerings: "...",   # or null
  sender_proof:     "...",   # or null
  recipients: [              # each entry always has a name (user-provided or auto-derived)
    { email: "...", name: "...", company: "...", title: "...", domain: "..." },
    ...
  ],
  campaign_purpose: "...",
  recipient_fields: {
    name:    true,           # ALWAYS true — either user-provided or auto-derived from email prefix
    company: true/false,
    title:   true/false,
    domain:  true/false,
  }
}

Step 1 — Verify Recipient Emails

Always verify before sending to >10 recipients.

Use the bundled script (MANDATORY)

source ~/.zshrc

# Option A: inline emails
python3 scripts/verify_emails.py alice@example.com bob@gmail.com

# Option B: from file (TXT/CSV/JSON)
python3 scripts/verify_emails.py --file leads.csv

# Option C: override column detection
python3 scripts/verify_emails.py --file leads.csv --email-column "Email Address"

Script flags:

Output: JSON on stdout with categorized results:

{
  "total": 5,
  "valid": [{"email": "...", "status": "VALID"}],
  "invalid": [...],
  "domain_error": [...],
  "unknown": [...],
  "unchecked": [...]
}

Email Status Values

Filtering guidance: Conservative = VALID only. Aggressive = VALID + UNKNOWN.

Behavior Rules

• Never report results while UNCHECKED entries remain (unless timeout)
• Show progress during polls: "Verifying... X/total processed"
• Ask before filtering: "Found N undeliverable addresses. Remove them?"
• Credit error = stop immediately
• UNKNOWN is not a hard block — explain the tradeoff

API Details (edge cases only)

• Submit: POST /sirius/api/biz/email/verification — body: {"emails": [...]}
• Poll: GET /sirius/api/biz/email/verification/task/{taskId}
• Max 10,000 emails per task; script auto-batches larger lists
• 120 req/min rate limit; on 429 wait 60s

Step 2 — Claim Free Pre-Warmed Mailbox

Run before creating any campaign. Each user gets one free mailbox (60 days, 90+ sender score).

Use the bundled script (MANDATORY)

source ~/.zshrc

# Claim (idempotent — safe to run multiple times)
python3 scripts/claim_free_mailbox.py

# JSON output for scripting
python3 scripts/claim_free_mailbox.py --json

What you get:

• Pre-warmed mailbox with 90+ sender score
• 60-day validity, no credit card required
• Idempotent: re-running returns the same mailbox
• stdout outputs just the email address (for piping)

Note: The free mailbox uses a randomly assigned domain (e.g. you@randomdomain.io) which may not match your company domain. If brand consistency matters, consider purchasing a dedicated domain at https://app.mailgo.ai.

Auto-integration

After claiming, use the returned email as --sender in Step 4:

SENDER=$(python3 scripts/claim_free_mailbox.py)
python3 scripts/run_campaign.py --sender "$SENDER" ...

API Details (edge cases only)

• Endpoint: POST /api/biz/benefits/assign-prewarm
• Auth: X-API-Key: {key}
• Response: {"code": 0, "data": "email@domain.com"}
• data: null = pool empty, contact support

Step 3 — Generate & Optimize Email Content

This is a knowledge-and-rewrite step. No API calls. No scripts.

Apply the 6-step optimization pipeline to user content, or generate from scratch.

Prerequisites for Generation — Use Session Context (CRITICAL)

All sender and recipient information was collected in Step 0.5. Do NOT ask again.

Read directly from session_context:

If session_context is missing (e.g. user jumped directly to Step 3), collect the missing fields inline — but only the ones not yet known.

Template Variables and Placeholder Rules (CRITICAL)

Mailgo uses #{...} placeholders that are resolved server-side at send time:

CRITICAL — Conditional Placeholder Rule:

• ONLY use a #{...} placeholder if the corresponding data is confirmed available (either from the file columns or user-provided inline data).
• If a field has NO data, NEVER use its #{...} placeholder. The placeholder will resolve to empty string at send time, creating ugly output like ，您好 or 关于 的合作.
• Exception: #{Name} is ALWAYS available. Every recipient has a name — either provided by the user or auto-derived from the email prefix in Step 0.5. Never fall back to "您好" when you have email addresses.
• For other fields, use a generic alternative:

Log placeholder decisions in the change summary:

Placeholders used: #{Name} (data available), #{Email} (always available)
Placeholders skipped: #{Company Name} (no data), #{Title} (no data), #{Domain} (no data)

Optimization Pipeline (execute ALL 6 steps, in order)

Step 3.1 — Normalize

• Plain text input → wrap in HTML skeleton (see below)
• HTML input → preserve structure

Step 3.2 — Spam Trigger Scan

• Scan subject + body against resources/spam-triggers.md
• Replace each trigger with neutral alternative
• Log every replacement

Key replacements (most common):

Full replacement table: resources/spam-triggers.md

Step 3.3 — HTML Cleanup

• Remove: <script>, <style>, <meta>, <link>, <iframe>, <embed>, <object>
• Remove: event handlers (onclick, onload, etc.)
• Convert <style> blocks → inline styles, then remove block
• Remove: HTML comments, CSS !important, base64 images
• Ensure: all <img> have alt attributes

Step 3.4 — Structure Check

• Text-to-image ratio > 60% text (warn if image-heavy)
• Cold email target: < 150 words (flag if > 200)
• One CTA only (suggest consolidation if multiple)
• Placeholder Data Validation — scan all #{...} in the content against session_context.recipient_fields:
  • #{Name} and #{Email} → always safe, never touch
  • #{Company Name} → if recipient_fields.company == false: replace with generic text (e.g. 贵公司 / your company); log the replacement
  • #{Domain} → if recipient_fields.domain == false: remove the sentence containing it entirely; log the removal
  • #{Title} → if recipient_fields.title == false: replace with generic phrasing or omit; log the replacement
  • If data IS available for a placeholder: preserve it unchanged

Step 3.5 — Link Audit

• Replace URL shorteners (bit.ly, t.co, tinyurl, goo.gl, ow.ly) with full URLs
• Warn if > 3 links in cold email
• Remove javascript: and data: URLs

Step 3.6 — Final Polish

• Add soft opt-out line if missing (see below)
• Verify HTML is well-formed
• Write to /tmp/email_optimized_<timestamp>.html

Content Generation (from scratch)

Generate 4 subject line variants for A/B testing. Adapt based on available data:

If #{Company Name} data IS available:

If #{Company Name} data is NOT available:

Subject rules: 40-50 chars, always personalize with #{Name} (always available); use #{Company Name} only if data available. No ALL CAPS, no spam triggers, no fake Re:/Fwd:.

Body structure (adapt based on available fields):

1. Personal opener (1 sentence)
   - ALWAYS use "#{Name}，您好：" — #{Name} is always available (user-provided or auto-derived)
   - WITH #{Company Name}: reference it in opener
   - WITHOUT #{Company Name}: use generic "贵公司" / "your company" or omit

2. Value bridge (1-2 sentences) — connect their situation to your offering
3. Proof point (1 sentence) — specific metric or case study (use sender_proof if available)
4. Soft CTA (1 sentence) — question, not demand
5. Signature — use actual sender_name + sender_title + sender_company (NEVER use placeholders like [Name])
6. Soft opt-out

Body rules: under 150 words, conversational tone, one CTA. All sender info in signature must be real data, not placeholders.

Select industry template from resources/industry-templates.md based on user's offerings.

HTML Skeleton

Use for plain-text wrapping or building from scratch:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body style="margin:0; padding:20px; font-family:Arial, sans-serif; font-size:14px; line-height:1.6; color:#333333;">
  <div style="max-width:600px; margin:0 auto;">

    <!-- EMAIL CONTENT HERE -->

  </div>
</body>
</html>

Soft Opt-Out Line

Always add after signature if missing:

P.S. If this isn't relevant, just reply and let me know — I won't reach out again.

Change Summary Format

Email Optimization Complete
---
Industry template: SaaS / Software (matched from "AI deployment platform")
Sender info: Zhang Wei, Sales Director, TirePro Technologies (www.tirepro.com)
Recipient data available: name (auto-derived from email prefix), company (no), title (no), domain (no)
Placeholders used: #{Name} (auto-derived from email prefix — e.g. alice.smith@co.com → "Alice Smith")
Placeholders skipped: #{Company Name}, #{Title}, #{Domain} (no data — generic wording used)
Spam triggers replaced: 3
  - "free trial" → "trial period"
  - "Click here" → "Learn more"
  - "Act now" → "When you're ready"
HTML issues fixed: 1
  - Removed <script> tag
Structure: 118 words (OK)
Links: 2 (OK)
Opt-out: Added
Subjects generated: 4 variants

Output: /tmp/email_optimized_1711468800.html
→ Use with: --body-file /tmp/email_optimized_1711468800.html

Severity Levels

Behavior Rules

• Run automatically before every campaign send, even if not asked. Report "0 issues found" if clean.
• If user says "don't change my content": scan and report only, do not modify.
• Never change meaning. Replace words, don't rewrite paragraphs.
• Placeholder rule differs by scenario:
  • Generating content from scratch: NEVER write a #{...} placeholder unless the corresponding recipient_fields value is true. Use the generic alternatives from the Placeholder Rules table instead.
  • Optimizing existing content: if the content already contains a #{...} placeholder with NO data available, MUST replace it with the generic alternative (Step 3.4 Placeholder Data Validation). Do not silently preserve it — an unresolved placeholder will appear as a blank gap to the recipient.
  • Exception: #{Name} and #{Email} are always safe — never remove or replace them.
• NEVER use [bracketed placeholders] like [Name], [Company], [Title] in final email output. These must be replaced with actual sender data or omitted. They are template authoring aids, not send-time variables.
• Always use actual sender info (name, title, company, website) in the email signature — collected from the user in the Prerequisites step.
• Write HTML to /tmp/email_optimized_<timestamp>.html and use via --body-file.

Step 4 — Create & Send Campaign

Use the bundled script (MANDATORY)

source ~/.zshrc

# Option A: inline recipients
python3 scripts/run_campaign.py \
    --sender "claimed@mailbox.com" \
    --subject "Quick question about #{Company Name}" \
    --body-file /tmp/email_optimized_1711468800.html \
    --recipients "alice@example.com,bob@test.com" \
    --campaign-name "SaaS Outreach Mar 2026" \
    --daily-limit 50

# Option B: recipients from file (CSV/XLSX/TXT/JSON)
python3 scripts/run_campaign.py \
    --sender "claimed@mailbox.com" \
    --subject "Quick question about #{Company Name}" \
    --body-file /tmp/email_optimized_1711468800.html \
    --recipients-file leads.xlsx \
    --campaign-name "SaaS Outreach Mar 2026"

Script flags:

Output: JSON summary with campaignId, emailContentId, lead counts, activation status.

Agent Decision Framework

All campaign inputs were collected in Step 0.5. Use session_context directly.

From session_context (never ask again):

• Recipients — session_context.recipients
• Purpose/goal — session_context.campaign_purpose
• Sender info — sender_company, sender_name, sender_title, sender_website, sender_offerings, sender_proof
• Recipient field availability — recipient_fields.{name, company, title, domain}

Auto-inferred (never ask):

• Sender email — auto-assigned from Step 2 (free mailbox)
• Subject — generate from campaign_purpose (Step 3), using only placeholders with confirmed recipient_fields
• Body — generate personalized HTML (Step 3), respecting recipient_fields availability
• Campaign name — derived from campaign_purpose + current month (e.g. "Tire Outreach Mar 2026")
• Schedule — Mon-Fri 9am-6pm, Asia/Singapore timezone
• Daily limit — 50 for new accounts
• Tracking — open + click ON

Decision Flow

0.5. [Already done] All info collected upfront — use session_context throughout
1.   Verify recipients (Step 1) if > 10 emails
2.   Claim mailbox (Step 2) if no sender specified
3.   Generate & optimize content (Step 3) — use ONLY placeholders with confirmed recipient_fields
4.   Run scripts/run_campaign.py (Step 4) — pass all available recipient fields
5.   Report: campaignId, name, lead count, activation status

API Reference (edge cases only)

Campaign creation is a 4-step sequential flow handled by the script:

Step 4a — Upload content:  POST /campaign/api/biz/mailgo/email/content/upload
Step 4b — Create campaign: POST /campaign/api/biz/mailgo/campaign/save
Step 4c — Add leads:       POST /campaign/api/biz/mailgo/leads/add
Step 4d — Activate:        POST /campaign/api/biz/mailgo/campaign/operate

Fall back to raw API only for: updating existing campaigns or adding leads from contact groups.

Step 5 — Manage Campaign Lifecycle

Use the bundled script (MANDATORY)

source ~/.zshrc

# Activate / Pause / Delete
python3 scripts/campaign_control.py activate <campaignId>
python3 scripts/campaign_control.py pause    <campaignId>
python3 scripts/campaign_control.py delete   <campaignId>   # confirm with user first!

# List campaigns
python3 scripts/campaign_control.py list                    # all
python3 scripts/campaign_control.py list --status 1         # active
python3 scripts/campaign_control.py list --status 0         # paused
python3 scripts/campaign_control.py list --name "outreach"  # fuzzy search

# Get campaign detail
python3 scripts/campaign_control.py info <campaignId>

Decision Flow

User says "stop/pause/resume/delete <campaign>"

1. Know campaign ID?
   YES → run script directly
   NO  → run: scripts/campaign_control.py list --status 1,0
         show results, ask user to pick one

2. If delete → confirm: "Delete campaign '{name}'? This cannot be undone."

3. Run script, report: "Campaign '{name}' (ID: {id}) is now {STATUS}."

Campaign Status Reference

State transitions: DRAFT->ACTIVE, ACTIVE<->PAUSE, any->deleted

Abnormal States (abnormalType)

Step 6 — View Campaign Reports

Use the bundled script (MANDATORY)

source ~/.zshrc

# Overview stats
python3 scripts/campaign_report.py overview <campaignId>

# Per-round breakdown
python3 scripts/campaign_report.py rounds <campaignId>

# Daily progress (requires date range)
python3 scripts/campaign_report.py daily <campaignId> --start 2026-03-25 --end 2026-03-31

# List replies (metadata only)
python3 scripts/campaign_report.py replies <campaignId>

# List replies + read plain-text body of each reply
python3 scripts/campaign_report.py replies <campaignId> \
    --sender "sender@mailbox.com" \
    --read-content

# Raw JSON output
python3 scripts/campaign_report.py --json overview <campaignId>

Output Format

Always show rates, not raw numbers alone:

Campaign: "Q1 Outreach" (ID: 123456)  Status: ACTIVE
Leads: 500 total | 250 completed | 30 in progress | 200 not yet | 20 failed

  Sent:       450
  Delivered:  420  (93.3%)
  Opened:     180  (42.9%)
  Replied:     35  ( 8.3%)
  Clicked:     65  (15.5%)
  Bounced:     30  ( 6.7%)

Deliverability Health Metrics

API Reference (for advanced queries)

Behavior Rules

• Default to overview. Drill into details only on explicit request.
• Always show rates alongside raw counts.
• If sent == 0: say "No emails sent yet" — do not divide by zero.
• If no campaign ID: list campaigns first, offer to drill into one.
• If openClick == 0: tracking was disabled — say so.
• If replied > 0 in overview: proactively suggest reading replies:

  💬 X reply(ies) detected. Run the following to read them:
  python3 scripts/campaign_report.py replies <campaignId> \
      --sender <senderEmail> --read-content
  

Global Error Handling

Global Behavior Rules

1. Script-first: Always use bundled scripts. Never reimplement API calls inline.
2. Verify before send: Always run Step 1 for campaigns with >10 recipients.
3. Optimize before send: Always run Step 3 before sending, even if not explicitly asked. Report "0 issues" if clean.
4. Confirm destructive actions: Always confirm before delete. Campaign deletion is irreversible via API.
5. Security: Never handle API keys in chat. User must create token in Personal Tokens and set as environment variable.
6. Zero dependencies: All scripts use Python stdlib only (urllib, json, csv, ssl). No pip install required (except optional openpyxl for .xlsx files).