Generate a Cold-Email Pitch

POST /api/visibility/cold-email

Authentication: Required

Generate cold-email content for an outbound sales motion in a single sync request. Returns a ready-to-send email plus structured fields a rep can mix and match for follow-ups, and a scanLandingUrl deep link that triggers a free Visibility Scan Preview when the recipient clicks.

This endpoint is one half of Pendium's outbound stack — the cheap, batch top-of-funnel. The other half is Trigger a Visibility Scan Preview, the deeper public report you escalate to once a recipient engages. Both are built for GTM partners, in-house GTM teams, and consultants/agencies running outbound on their own Pendium account. Neither endpoint is the ongoing-monitoring product — paying customers' managed agents run scheduled scans through POST /api/visibility/scan and read results from GET /api/visibility/report. Use those for in-app dashboards, recurring measurement, and score history; use this endpoint and the Scan Preview for outbound prospecting.

Category-aware. The endpoint supports five base prompt framings (default, shopify, ecommerce, yelp, gbp) so the same API works for DTC stores, broader online retail, local services, and any business that lives in Google Business Profile. The default category auto-detects Shopify and gracefully falls back to a generic-store prompt for non-Shopify URLs.

Voice-tunable. Pass a named voice preset or your own freeform voice text and the email register adapts.

Override-aware. Pass notes with any open-ended instructions and they're injected at the top of the prompt with override priority over the voice and anti-slop rules.

Request body

{
  "url": "https://allbirds.com",
  "category": "shopify",
  "voice": "founder",
  "notes": "We're targeting their Black Friday window — emphasize urgency.",
  "recipientFirstName": "Dan",
  "model": "gemini-flash"
}

Categories

is_shopify in the response reflects whether a catalog was actually fetched, independent of category — a shopify category can still produce isShopify: false if the storefront fetch failed.

Voice presets

Each preset bundles character + tone + vibe into a single named choice:

Pass any other string and the endpoint treats it as your own custom voice instructions. The voiceLabel field in the response tells you whether your input matched a preset (preset name), was treated as custom ("custom"), or wasn't supplied ("default").

Notes — when to use it

Notes outrank the voice block, the category instructions, and the anti-slop guards if anything conflicts. Reach for notes when:

• The default category framing is close but you want to nudge it (e.g. "this brand sells refurbished electronics — frame the pitch around AI assistants steering shoppers away from refurbs and how to win that consideration").
• You're running a campaign with shared context (e.g. "all of these emails are going out the week before Black Friday — tilt the offer toward urgency without using the word 'urgency'").
• A specific batch needs a tone constraint (e.g. "do not mention competitors by name in the email body — keep them in competitiveIntel only").

Don't use notes to fight the anti-slop guards — those exist because cold-email tells like "I hope this finds you well" tank reply rates. The override is for nuance, not to disable quality controls.

Example

curl -X POST https://pendium.ai/api/visibility/cold-email \
  -H "Content-Type: application/json" \
  -H "x-api-key: pendium_xxxxxxxxxxxx" \
  -d '{
    "url": "https://allbirds.com",
    "category": "shopify",
    "voice": "founder"
  }'

Response

The email object is split into five fields so the rep never has to edit anything before sending. Concatenate them with blank lines between (greeting → opening → body → ps?); the outbound tool appends the rep's signature.

{
  "success": true,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "url": "https://allbirds.com",
  "shopDomain": "allbirds.com",
  "isShopify": true,
  "category": "shopify",
  "voice": "founder",
  "voiceLabel": "founder",
  "notesApplied": false,
  "recipientFirstName": "Dan",
  "model": "gemini-flash",
  "brandName": "Allbirds",
  "introHook": "Your Tree Runners are everywhere on TikTok, but ChatGPT keeps recommending Veja first.",
  "competitiveIntel": {
    "competitor": "Rothy's",
    "angle": "Rothy's is dominating AI answers about sustainable everyday sneakers — Allbirds shows up second or third in most prompt shapes shoppers actually use."
  },
  "funFacts": [
    "47 best-sellers across 9 collections, but the Tree line carries almost all of the AI answer share."
  ],
  "findings": [
    {
      "title": "Missing third-party Wirecutter coverage in 2025",
      "detail": "AI assistants lean heavily on Wirecutter for sustainable-footwear queries, and your last cited mention is from 2023."
    }
  ],
  "email": {
    "subject": "Your Tree Runners aren't winning AI search yet",
    "greeting": "hey Dan,",
    "opening": "spent ten minutes in your catalog and one thing stood out: your Tree Runners are everywhere on TikTok, but ChatGPT keeps recommending Veja first.",
    "body": "we just ran a Pendium scan on your store — Rothy's is winning three of the four big AI assistants for sustainable-everyday-sneaker queries, and the Switch line barely surfaces at all. it's not positioning, it's a citation gap. happy to send the per-query breakdown — want it?",
    "ps": "P.S. cold email — reply 'no' if you don't want to hear from me again."
  },
  "grounded": false,
  "scanLandingUrl": "https://pendium.ai/?report=https%3A%2F%2Fallbirds.com",
  "generatedAt": "2026-05-06T18:42:11.000Z"
}

Bracket-free guarantee. Every email field — subject, greeting, opening, body, ps — is fully ready to send as text. No [Your name] placeholders, no {{firstName}} merge tokens, no brackets of any kind. Pass recipientFirstName to get a personalised greeting; otherwise the greeting uses a no-name fallback ("hey,"). Sender signature is appended by the outbound tool.

Key fields

Refetch a previous pitch

GET /api/visibility/cold-email?uuid=…

Returns the same JSON shape as the POST response, including the same scanLandingUrl. Useful for CRM idempotency, support, and replaying a pitch into a different outbound tool without re-paying for LLM cost. Authorization: caller must own the pitch (or be a platform admin).

What to do with this data

The email is fully ready to send — every field is plain text with no brackets, no placeholders, no merge tokens. The simplest integration is:

{greeting}

{opening}

{body}

{ps if not null}

Pass that into your outbound tool's body field; the tool appends the rep's signature. Use scanLandingUrl as the call-to-action link when you want to include it (often left out of first emails for deliverability and saved for follow-ups).

The structured fields (introHook, competitiveIntel, funFacts, findings) exist so the rep can mix and match for follow-ups in the same thread, A/B different openers, or pull individual hooks into a CRM merge field. When a recipient engages, escalate to the full Visibility Scan Preview for the same URL.