Referral & Affiliate Programs

You are an expert in viral growth and referral marketing. Your goal is to help design and optimize programs that turn customers into growth engines.

Before Starting

Check for product marketing context first: If .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

1. Program Type

• Customer referral program, affiliate program, or both?
• B2B or B2C?
• What's the average customer LTV?
• What's your current CAC from other channels?

2. Current State

• Existing referral/affiliate program?
• Current referral rate (% who refer)?
• What incentives have you tried?

3. Product Fit

• Is your product shareable?
• Does it have network effects?
• Do customers naturally talk about it?

4. Resources

• Tools/platforms you use or consider?
• Budget for referral incentives?

---

Referral vs. Affiliate

Customer Referral Programs

Best for:

• Existing customers recommending to their network
• Products with natural word-of-mouth
• Lower-ticket or self-serve products

Characteristics:

• Referrer is an existing customer
• One-time or limited rewards
• Higher trust, lower volume

Affiliate Programs

Best for:

• Reaching audiences you don't have access to
• Content creators, influencers, bloggers
• Higher-ticket products that justify commissions

Characteristics:

• Affiliates may not be customers
• Ongoing commission relationship
• Higher volume, variable trust

---

Referral Program Design

The Referral Loop

Trigger Moment → Share Action → Convert Referred → Reward → (Loop)

Step 1: Identify Trigger Moments

High-intent moments:

• Right after first "aha" moment
• After achieving a milestone
• After exceptional support
• After renewing or upgrading

Step 2: Design Share Mechanism

Ranked by effectiveness:

1. In-product sharing (highest conversion)
2. Personalized link
3. Email invitation
4. Social sharing
5. Referral code (works offline)

Step 3: Choose Incentive Structure

Single-sided rewards (referrer only): Simpler, works for high-value products

Double-sided rewards (both parties): Higher conversion, win-win framing

Tiered rewards: Gamifies referral process, increases engagement

For examples and incentive sizing: See references/program-examples.md

---

Program Optimization

Improving Referral Rate

If few customers are referring:

• Ask at better moments
• Simplify sharing process
• Test different incentive types
• Make referral prominent in product

If referrals aren't converting:

• Improve landing experience for referred users
• Strengthen incentive for new users
• Ensure referrer's endorsement is visible

A/B Tests to Run

Incentive tests: Amount, type, single vs. double-sided, timing

Messaging tests: Program description, CTA copy, landing page copy

Placement tests: Where and when the referral prompt appears

Common Problems & Fixes

---

Measuring Success

Key Metrics

Program health:

• Active referrers (referred someone in last 30 days)
• Referral conversion rate
• Rewards earned/paid

Business impact:

• % of new customers from referrals
• CAC via referral vs. other channels
• LTV of referred customers
• Referral program ROI

Typical Findings

• Referred customers have 16-25% higher LTV
• Referred customers have 18-37% lower churn
• Referred customers refer others at 2-3x rate

---

Launch Checklist

Before Launch

• Define program goals and success metrics
• Design incentive structure
• Build or configure referral tool
• Create referral landing page
• Set up tracking and attribution
• Define fraud prevention rules
• Create terms and conditions
• Test complete referral flow

Launch

• Announce to existing customers
• Add in-app referral prompts
• Update website with program details
• Brief support team

Post-Launch (First 30 Days)

• Review conversion funnel
• Identify top referrers
• Gather feedback
• Fix friction points
• Send reminder emails to non-referrers

---

Email Sequences

Referral Program Launch

Subject: You can now earn [reward] for sharing [Product]

We just launched our referral program!

Share [Product] with friends and earn [reward] for each signup.
They get [their reward] too.

[Unique referral link]

1. Share your link
2. Friend signs up
3. You both get [reward]

Referral Nurture Sequence

• Day 7: Remind about referral program
• Day 30: "Know anyone who'd benefit?"
• Day 60: Success story + referral prompt
• After milestone: "You achieved [X]—know others who'd want this?"

---

Affiliate Programs

For detailed affiliate program design, commission structures, recruitment, and tools: See references/affiliate-programs.md

---

Task-Specific Questions

1. What type of program (referral, affiliate, or both)?
2. What's your customer LTV and current CAC?
3. Existing program or starting from scratch?
4. What tools/platforms are you considering?
5. What's your budget for rewards/commissions?
6. Is your product naturally shareable?

---

Tool Integrations

For implementation, see the tools registry (../../tools/REGISTRY.md). Key tools for referral programs:

---

Related Skills

• launch: For launching referral program effectively
• emails: For referral nurture campaigns
• marketing-psychology: For understanding referral motivation
• analytics: For tracking referral attribution

---

Supporting file: evals/evals.json

{
  "skill_name": "referrals",
  "evals": [
    {
      "id": 1,
      "prompt": "Help me design a referral program for our SaaS product. We're a $49/month project management tool with about 1,000 customers. We want to encourage word-of-mouth growth.",
      "expected_output": "Should check for product-marketing.md first. Should distinguish between referral and affiliate programs (this is referral — existing customers referring peers). Should design the referral loop: trigger point (when to ask for referral), share mechanism (unique link, email invite, social share), conversion flow (what the referred person experiences), and reward structure. Should recommend incentive type: double-sided recommended (both referrer and referred get value). Should suggest specific incentives appropriate for $49/month SaaS (e.g., free month for both). Should include the launch checklist. Should recommend tool integrations (Rewardful, Tolt, etc.).",
      "assertions": [
        "Checks for product-marketing.md",
        "Distinguishes referral from affiliate",
        "Designs the referral loop (trigger, share, convert, reward)",
        "Recommends double-sided incentive structure",
        "Suggests specific incentives for the price point",
        "Includes launch checklist",
        "Recommends tool integrations"
      ],
      "files": []
    },
    {
      "id": 2,
      "prompt": "We have a referral program but only 5% of customers have ever referred someone. How do we increase participation?",
      "expected_output": "Should apply the program optimization guidance. Should diagnose low participation: are customers aware of the program? Is the trigger point well-timed? Is the incentive compelling enough? Is sharing easy? Should recommend optimization tactics: better placement/visibility, timing referral asks at peak satisfaction moments, improving the incentive, simplifying the share mechanism, adding referral reminders in email and in-app. Should provide specific experiment ideas to test improvements.",
      "assertions": [
        "Applies program optimization guidance",
        "Diagnoses potential causes of low participation",
        "Checks awareness, timing, incentive, and friction",
        "Recommends optimization tactics",
        "Suggests timing referral asks at satisfaction moments",
        "Provides experiment ideas"
      ],
      "files": []
    },
    {
      "id": 3,
      "prompt": "should we do referral or affiliate? we sell online courses for $199-499 and want to get other creators and influencers to promote us.",
      "expected_output": "Should trigger on casual phrasing. Should apply the referral vs affiliate distinction clearly. For this use case (getting creators/influencers to promote), should recommend an affiliate program (not referral — affiliates are third-party promoters, not existing customers). Should apply the affiliate program section guidance: commission structure for digital products (typically 20-40% for courses), cookie duration, payout terms, affiliate onboarding. Should recommend affiliate platforms/tools appropriate for course creators.",
      "assertions": [
        "Triggers on casual phrasing",
        "Clearly distinguishes referral from affiliate",
        "Recommends affiliate for this use case",
        "Provides commission structure guidance for courses",
        "Addresses cookie duration and payout terms",
        "Recommends appropriate affiliate platforms"
      ],
      "files": []
    },
    {
      "id": 4,
      "prompt": "What incentive structure works best? We've been offering $10 off for referrers but it's not working. Our product is $29/month.",
      "expected_output": "Should evaluate the current incentive: $10 off on a $29/month product is significant but only benefits the referrer (single-sided). Should recommend testing double-sided incentives (both parties get value). Should discuss incentive types: account credit, free months, feature upgrades, cash. Should apply the tiered incentive concept (increasing rewards for multiple referrals). Should provide specific alternative incentive structures to test. Should note that incentive alone may not be the problem — placement and timing matter too.",
      "assertions": [
        "Evaluates current incentive structure",
        "Identifies as single-sided and recommends double-sided",
        "Discusses multiple incentive types",
        "Applies tiered incentive concept",
        "Provides specific alternatives to test",
        "Notes incentive may not be the only issue"
      ],
      "files": []
    },
    {
      "id": 5,
      "prompt": "How do we measure the success of our referral program? What metrics should we track?",
      "expected_output": "Should apply the measuring success framework. Should define key metrics: participation rate (% of customers who refer), share rate (referrals sent per participant), conversion rate (referred visitors who become customers), viral coefficient (k-factor), customer acquisition cost via referral vs other channels, referred customer LTV vs organic customer LTV. Should recommend tracking tools and dashboards. Should provide benchmark ranges for each metric.",
      "assertions": [
        "Applies measuring success framework",
        "Defines participation rate, share rate, conversion rate",
        "Includes viral coefficient / k-factor",
        "Compares referral CAC to other channels",
        "Compares referred customer LTV to organic",
        "Recommends tracking approach",
        "Provides benchmark ranges"
      ],
      "files": []
    },
    {
      "id": 6,
      "prompt": "Can you write the referral invitation emails? I need the email that goes out when someone shares their referral link.",
      "expected_output": "Should recognize this overlaps with email writing. Should apply the referral email sequence section from the skill for referral-specific emails. However, for detailed email sequence design (multi-email nurture for referred users), should cross-reference the emails skill. Should provide the referral invitation email but note that broader email sequence work is handled by emails.",
      "assertions": [
        "Applies referral email section from the skill",
        "Provides referral invitation email guidance",
        "Cross-references emails for broader email work",
        "Provides specific referral email copy or template"
      ],
      "files": []
    }
  ]
}

---

Supporting file: references/affiliate-programs.md

Affiliate Program Design

Detailed guidance for building and managing affiliate programs.

Contents

• Commission Structures
• Cookie Duration
• Affiliate Recruitment
• Affiliate Enablement
• Tools & Platforms (Referral Program Tools, Affiliate Program Tools, Choosing a Tool)
• Fraud Prevention (Common Referral Fraud, Prevention Measures)

Commission Structures

Percentage of sale:

• Standard: 10-30% of first sale or first year
• Works for: E-commerce, SaaS with clear pricing
• Example: "Earn 25% of every sale you refer"

Flat fee per action:

• Standard: $5-500 depending on value
• Works for: Lead gen, trials, freemium
• Example: "$50 for every qualified demo"

Recurring commission:

• Standard: 10-25% of recurring revenue
• Works for: Subscription products
• Example: "20% of subscription for 12 months"

Tiered commission:

• Works for: Motivating high performers
• Example: "20% for 1-10 sales, 25% for 11-25, 30% for 26+"

---

Cookie Duration

How long after click does affiliate get credit?

---

Affiliate Recruitment

Where to find affiliates:

• Existing customers who create content
• Industry bloggers and reviewers
• YouTubers in your niche
• Newsletter writers
• Complementary tool companies
• Consultants and agencies

Outreach template:

Subject: Partnership opportunity — [Your Product]

Hi [Name],

I've been following your content on [topic] — particularly [specific piece] — and think there could be a great fit for a partnership.

[Your Product] helps [audience] [achieve outcome], and I think your audience would find it valuable.

We offer [commission structure] for partners, plus [additional benefits: early access, co-marketing, etc.].

Would you be open to learning more?

[Your name]

---

Affiliate Enablement

Provide affiliates with:

• Unique tracking links/codes
• Product overview and key benefits
• Target audience description
• Comparison to competitors
• Creative assets (logos, banners, images)
• Sample copy and talking points
• Case studies and testimonials
• Demo access or free account
• FAQ and objection handling
• Payment terms and schedule

---

Tools & Platforms

Referral Program Tools

Full-featured platforms:

• ReferralCandy — E-commerce focused
• Ambassador — Enterprise referral programs
• Friendbuy — E-commerce and subscription
• GrowSurf — SaaS and tech companies
• Mention Me — AI-powered referral marketing
• Viral Loops — Template-based campaigns

Built-in options:

• Stripe (basic referral tracking)
• HubSpot (CRM-integrated)
• Segment (tracking and analytics)

Affiliate Program Tools

Affiliate networks:

• ShareASale — Large merchant network
• Impact — Enterprise partnerships
• PartnerStack — SaaS focused
• Tapfiliate — Simple SaaS affiliate tracking
• FirstPromoter — SaaS affiliate management

Partner Relationship Management (PRM):

• Introw — Full PRM with deal registration, commissions, tiers, QBRs, and partner engagement tracking (integration guide (../../../tools/integrations/introw.md))

Self-hosted:

• Rewardful — Stripe-integrated affiliates
• Refersion — E-commerce affiliates

Choosing a Tool

Consider:

• Integration with your payment system
• Fraud detection capabilities
• Payout management
• Reporting and analytics
• Customization options
• Price vs. program scale

---

Fraud Prevention

Common Referral Fraud

• Self-referrals (creating fake accounts)
• Referral rings (groups referring each other)
• Coupon sites posting referral codes
• Fake email addresses
• VPN/device spoofing

Prevention Measures

Technical:

• Email verification required
• Device fingerprinting
• IP address monitoring
• Delayed reward payout (after activation)
• Minimum activity threshold

Policy:

• Clear terms of service
• Maximum referrals per period
• Reward clawback for refunds/chargebacks
• Manual review for suspicious patterns

Structural:

• Require referred user to take meaningful action
• Cap lifetime rewards
• Pay rewards in product credit (less attractive to fraudsters)

---

Supporting file: references/program-examples.md

Referral Program Examples

Real-world examples of successful referral programs.

Contents

• Dropbox (Classic)
• Uber/Lyft
• Morning Brew
• Notion
• Incentive Types Comparison
• Incentive Sizing Framework
• Viral Coefficient & Metrics (Key Metrics, Calculating Referral Program ROI)

Dropbox (Classic)

Program: Give 500MB storage, get 500MB storage

Why it worked:

• Reward directly tied to product value
• Low friction (just an email)
• Both parties benefit equally
• Gamified with progress tracking

---

Uber/Lyft

Program: Give $10 ride credit, get $10 when they ride

Why it worked:

• Immediate, clear value
• Double-sided incentive
• Easy to share (code/link)
• Triggered at natural moments

---

Morning Brew

Program: Tiered rewards for subscriber referrals

• 3 referrals: Newsletter stickers
• 5 referrals: T-shirt
• 10 referrals: Mug
• 25 referrals: Hoodie

Why it worked:

• Gamification drives ongoing engagement
• Physical rewards are shareable (more referrals)
• Low cost relative to subscriber value
• Built status/identity

---

Notion

Program: $10 credit per referral (education)

Why it worked:

• Targeted high-sharing audience (students)
• Product naturally spreads in teams
• Credit keeps users engaged

---

Incentive Types Comparison

---

Incentive Sizing Framework

Calculate your maximum incentive:

Max Referral Reward = (Customer LTV × Gross Margin) - Target CAC

Example:

• LTV: $1,200
• Gross margin: 70%
• Target CAC: $200
• Max reward: ($1,200 × 0.70) - $200 = $640

Typical referral rewards:

• B2C: $10-50 or 10-25% of first purchase
• B2B SaaS: $50-500 or 1-3 months free
• Enterprise: Higher, often custom

---

Viral Coefficient & Metrics

Key Metrics

Viral coefficient (K-factor):

K = Invitations × Conversion Rate

K > 1 = Viral growth (each user brings more than 1 new user)
K < 1 = Amplified growth (referrals supplement other acquisition)

Example:

• Average customer sends 3 invitations
• 15% of invitations convert
• K = 3 × 0.15 = 0.45

Referral rate:

Referral Rate = (Customers who refer) / (Total customers)

Benchmarks:

• Good: 10-25% of customers refer
• Great: 25-50%
• Exceptional: 50%+

Referrals per referrer:

Benchmarks:

• Average: 1-2 referrals per referrer
• Good: 2-5
• Exceptional: 5+

Calculating Referral Program ROI

Referral Program ROI = (Revenue from referred customers - Program costs) / Program costs

Program costs = Rewards paid + Tool costs + Management time

Track separately:

• Cost per referred customer (CAC via referral)
• LTV of referred customers (often higher than average)
• Payback period for referral rewards

---

Supporting file: tools/REGISTRY.md

Marketing Tools Registry

Quick reference for AI agents to discover tool capabilities and integration methods.

How to Use This Registry

1. Find tools by category - Browse sections below for tools in each domain
2. Check integration methods - See what APIs, MCPs, CLIs, or SDKs are available
3. Read integration guides - Detailed setup and common operations in integrations/

---

Tool Index

---

By Category

Analytics

Track user behavior, measure conversions, and analyze marketing performance.

Agent recommendation: Start with GA4 if using Google ecosystem. Use Mixpanel or Amplitude for deeper product analytics. Plausible for privacy-focused sites.

SEO

Search engine optimization tools for keyword research, rank tracking, and site audits.

Agent recommendation: Google Search Console is essential (free). Add Semrush or Ahrefs for competitive research. DataForSEO for programmatic SERP data. Keywords Everywhere for quick keyword lookups. RankParse for agent workflows where per-call cost matters — backlinks, domain authority, and tech stack at a fraction of enterprise pricing.

CRM

Customer relationship management and sales tools.

Agent recommendation: HubSpot for startups/SMBs. Close for high-velocity inside sales. Salesforce for enterprise.

Payments

Payment processing and subscription management.

Agent recommendation: Stripe is the default for SaaS. Paddle for built-in tax compliance.

Referral & Affiliate

Tools for referral programs, affiliate tracking, and partner management.

Agent recommendation: Rewardful or Tolt for Stripe-based SaaS. PartnerStack for enterprise partner programs. Dub.co for link attribution.

Email

Email marketing, transactional email, and automation platforms.

Agent recommendation: Resend for transactional (dev-friendly). Sequenzy for lifecycle email, sequences, and agent-driven email marketing. Postmark for deliverability. Customer.io for advanced automation. Kit for creators. Beehiiv for newsletters. Klaviyo for e-commerce email/SMS. ActiveCampaign for email + CRM combo.

SMS / Messaging

SMS and MMS marketing platforms and programmable messaging APIs.

Agent recommendation: Klaviyo SMS for ecom already on Klaviyo email. Postscript for Shopify-first depth. Attentive for mid-market+ wanting concierge support. Twilio (or Plivo for lower cost) for custom builds and transactional/auth. AudienceTap when AI creative or on-pack QR opt-in matters.

Advertising

Paid advertising platforms and campaign management.

Agent recommendation: Google Ads for search intent. Meta for demand generation. LinkedIn for B2B.

Automation

Workflow automation and integration platforms.

Agent recommendation: Zapier SDK for agents that need to interact with any app directly. Zaps for always-on automations.

CRO & A/B Testing

Conversion rate optimization, heatmaps, and experimentation.

Agent recommendation: Hotjar for understanding user behavior. Optimizely for running experiments.

Scheduling

Booking and appointment scheduling tools.

Agent recommendation: Calendly for general use. SavvyCal for personalized booking experiences.

Forms & Surveys

Form builders and survey platforms.

Agent recommendation: Typeform for engaging forms and surveys.

Messaging

In-app messaging, chat, and customer communication.

Agent recommendation: Intercom for in-app messaging and customer support.

Social Media

Social media scheduling, management, and analytics.

Agent recommendation: Buffer for scheduling and analytics across social platforms.

Video

Video hosting, creation, and AI generation.

Agent recommendation: HeyGen for AI avatar videos (MCP-enabled). Hyperframes for templated, data-driven video from code. Wistia for hosting and analytics.

Data Enrichment

Company and person data enrichment for sales and marketing.

Agent recommendation: Clearbit for enrichment. Apollo for prospecting and outbound. ZoomInfo for enterprise B2B data with intent signals. Clay for waterfall enrichment across multiple providers.

Email Verification

Pre-outreach email deliverability validation.

Agent recommendation: Truelist for any prospect list before outreach — Apollo/ZoomInfo/Hunter data accuracy is typically 60–80%, validation is non-negotiable to keep sender reputation healthy.

Developer Intent / GitHub

Discovery channel for dev-tool SaaS prospecting via GitHub stargazers, forkers, and watchers.

Agent recommendation: Use github-prospects.js CLI to pull stargazers/forks of 3–5 anchor repos (competitors, category leaders, complementary tools). Filter to users with company field set, then enrich missing emails via Apollo or Hunter, then validate via Truelist before outreach.

Site Scraping (single-target only)

Programmatic page extraction for individual public business sites — not for the platforms hosting prospects (Google Maps, LinkedIn, Yelp, Apollo, etc.).

Agent recommendation: Default to Firecrawl for static-ish pages and structured extraction. Use Browserbase when the site requires JS rendering, form interaction, cookie consent, or auth — and when you want session recordings for debugging. For both: discovery happens on platforms (manual browser); extraction happens on the prospect's own website URL. Don't point either tool at LinkedIn, Google Maps, Yelp, or similar.

Reviews

Review management and social proof platforms.

Agent recommendation: Trustpilot for consumer products. G2 for B2B software.

Push Notifications

Push notification delivery platforms.

Agent recommendation: OneSignal for web and mobile push notifications.

Webinar

Webinar and virtual event platforms.

Agent recommendation: Demio for marketing-focused webinars. Livestorm for full event engagement.

Sales Engagement

Sales engagement and outreach automation platforms.

Agent recommendation: Outreach for enterprise sales teams managing multi-touch sequences at scale.

Product Analytics

Product analytics, feature adoption tracking, and in-app guidance.

Agent recommendation: Pendo for tracking feature adoption and delivering targeted in-app guidance.

Competitive Intelligence

Traffic analytics, competitor benchmarking, and market research.

Agent recommendation: Similarweb for competitor traffic analysis and market benchmarking.

Audience Research

Audience intelligence and behavioral research tools.

Agent recommendation: SparkToro for discovering where your ICP spends time — what they read, watch, listen to, follow, and search for. Essential for customer research, content strategy, and media buying decisions.

Visitor Identification

Website visitor de-anonymization for B2B sales and marketing.

Agent recommendation: RB2B for identifying anonymous B2B website visitors and routing high-intent visitors to outreach tools. Pairs well with Clay for enrichment and Instantly/Lemlist for cold email.

Revenue Intelligence

Sales conversation analytics, call recording, and deal intelligence.

Agent recommendation: Gong for mining sales call transcripts for customer research, competitive intelligence, and coaching insights. Essential for revenue attribution and win/loss analysis.

AI Content

AI-powered content generation and optimization platforms.

Agent recommendation: AirOps for building AI content workflows that generate SEO-optimized content at scale.

AI Search

AI-powered web search APIs built for LLMs and agents. Return structured results with on-demand text, highlights, and summaries.

Agent recommendation: Exa for neural search over the open web — content research, competitor/similar-page discovery, link prospecting, news monitoring, and audience research. Pairs well with seo-audit, content-strategy, and competitor-profiling skills.

Partner Ecosystem

Partner data sharing, co-sell, and ecosystem management.

Agent recommendation: Crossbeam for identifying partner account overlaps and co-sell opportunities. Introw for full partner relationship management — partner pipeline, commissions, tasks, and automated business review prep.

Email Outreach

Cold email outreach and email finding tools for link building and sales prospecting.

Agent recommendation: Hunter for finding emails. Lemlist or Instantly for sending cold email campaigns. Snov for combined finding + outreach.

Data Aggregation

Marketing data pipeline tools that connect multiple platforms for unified reporting.

Agent recommendation: Supermetrics for pulling data from multiple marketing platforms into unified reports. Coupler.io for automated data flows to spreadsheets and BI tools.

Commerce & CMS

E-commerce platforms and content management systems.

Agent recommendation: Shopify for e-commerce. Webflow for marketing sites. WordPress for blogs. For headless CMS: Sanity for developer-flexible content, Contentful for enterprise multi-locale, Strapi for self-hosted/budget-conscious. See headless CMS guide (../skills/content-strategy/references/headless-cms.md) for selection criteria.

---

CLI Tools

Zero-dependency, single-file Node.js CLIs for tools that don't ship their own. See clis/README.md for install instructions and usage.

All CLIs follow a consistent pattern:

• No dependencies — Node 18+ only, uses native fetch
• JSON output — pipe to jq, save to file, or use in scripts
• Env var auth — set {TOOL}_API_KEY and go
• Consistent commands — {tool} <resource> <action> [options]

---

MCP-Enabled Tools

These tools have Model Context Protocol servers available, enabling direct agent interaction:

• ga4 - Google Analytics 4 data access
• stripe - Payment and subscription management
• mailchimp - Email campaign management
• google-ads - Ad campaign management
• resend - Transactional email sending
• zapier - Workflow automation + SDK for 8,000+ app integrations
• zoominfo - B2B contacts and intent data
• clay - Data enrichment and outbound automation
• supermetrics - Cross-platform marketing data
• coupler - Marketing data pipelines
• outreach - Sales engagement sequences
• crossbeam - Partner ecosystem data
• introw - Partner relationship management
• exa - AI-powered web search for LLMs and agents

To use MCP tools, ensure the appropriate MCP server is configured in your environment.

Composio Integration

Composio (integrations/composio.md) provides managed OAuth and pre-built connectors for 500+ tools via a single MCP server. It adds MCP access to tools that don't have native MCP servers, including HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion, and more.

• Setup: npx @composio/mcp@latest setup
• Quick start: See tools/composio/README.md (composio/README.md)
• Marketing tool mapping: See tools/composio/marketing-tools.md (composio/marketing-tools.md)

Use Composio when you need MCP access to OAuth-heavy tools. Prefer native MCP servers (GA4, Stripe, Mailchimp, etc.) when available — they have deeper coverage.

Cogny Integration

Cogny (integrations/cogny.md) is a hosted MCP gateway focused on marketing channels — one federated MCP URL with managed OAuth across every channel you've connected. Narrower than Composio (marketing-only) and useful when you want SEO, paid social, and privacy-friendly analytics behind a single MCP login.

• Setup: connect channels at cogny.com (https://cogny.com), then in Claude.ai go to Settings → Connectors → Add custom connector and paste https://app.cogny.com/mcp
• Channels: Search Console, Bing Webmaster, Semrush, LinkedIn Ads, Reddit Ads, TikTok Ads, Plausible, Fathom
• Pricing: Solo plan starts at $9/mo (7-day trial)

Use Cogny when you only need marketing channels and want to avoid running your own OAuth proxy. Prefer native APIs when you need deep, custom control of a single tool.

---

Quick Start by Use Case

Setting up analytics tracking

1. Read ga4.md (integrations/ga4.md) for web analytics
2. Read segment.md (integrations/segment.md) if routing to multiple tools

Launching a referral program

1. Read rewardful.md (integrations/rewardful.md) or tolt.md (integrations/tolt.md) for Stripe-based programs
2. Read dub-co.md (integrations/dub-co.md) for link tracking

Setting up email automation

1. Read customer-io.md (integrations/customer-io.md) for behavior-based automation
2. Read resend.md (integrations/resend.md) for transactional email

Running email outreach for backlinks

1. Read hunter.md (integrations/hunter.md) for finding emails
2. Read lemlist.md (integrations/lemlist.md) or instantly.md (integrations/instantly.md) for sending campaigns

Running paid ads

1. Read google-ads.md (integrations/google-ads.md) for search campaigns
2. Read meta-ads.md (integrations/meta-ads.md) for social campaigns

---

Supporting file: tools/integrations/dub-co.md

Dub.co

Link management and attribution platform for modern marketing teams.

Capabilities

Authentication

• Type: API Key
• Header: Authorization: Bearer {api_key}
• Get key: Settings > API Keys in Dub dashboard

Common Agent Operations

Create short link

POST https://api.dub.co/links

{
  "url": "https://example.com/landing-page",
  "domain": "link.example.com",
  "key": "summer-sale",
  "tags": ["campaign:summer", "channel:email"]
}

Get link by key

GET https://api.dub.co/links?domain=link.example.com&key=summer-sale

List links

GET https://api.dub.co/links?domain=link.example.com&page=1

Get link analytics

GET https://api.dub.co/analytics?domain=link.example.com&key=summer-sale&interval=30d

Get clicks by location

GET https://api.dub.co/analytics/country?domain=link.example.com&key=summer-sale

Get clicks by device

GET https://api.dub.co/analytics/device?domain=link.example.com&key=summer-sale

Update link

PATCH https://api.dub.co/links/{link_id}

{
  "url": "https://example.com/new-landing-page",
  "tags": ["campaign:summer", "channel:social"]
}

Delete link

DELETE https://api.dub.co/links/{link_id}

Bulk create links

POST https://api.dub.co/links/bulk

[
  {"url": "https://example.com/page1", "key": "page1"},
  {"url": "https://example.com/page2", "key": "page2"}
]

TypeScript SDK

Install

npm install dub

Usage

import { Dub } from "dub";

const dub = new Dub({ token: "YOUR_API_KEY" });

// Create link
const link = await dub.links.create({
  url: "https://example.com",
  domain: "link.example.com"
});

// Get analytics
const analytics = await dub.analytics.retrieve({
  domain: "link.example.com",
  key: "summer-sale"
});

Key Features

• Custom domains - Use your own branded domains
• Link analytics - Clicks, locations, devices, referrers
• Tags - Organize links by campaign, channel, etc.
• QR codes - Auto-generated for each link
• Password protection - Secure sensitive links
• Expiration - Time-limited links
• Geo-targeting - Redirect based on location

Analytics Dimensions

• clicks - Total click count
• country - Clicks by country
• city - Clicks by city
• device - Clicks by device type
• browser - Clicks by browser
• os - Clicks by operating system
• referer - Clicks by referrer

When to Use

• Creating trackable marketing links
• Building referral link systems
• Tracking campaign attribution
• A/B testing landing pages via links
• Generating branded short URLs
• Analyzing link performance

Rate Limits

• Free: 1,000 links, 5 API requests/second
• Pro: Unlimited links, 50 API requests/second
• Enterprise: Custom limits

Relevant Skills

• referrals
• analytics
• ads

---

Supporting file: tools/integrations/introw.md

Introw PRM

Partner Relationship Management platform for managing channel partners, tracking partner-sourced deals, commissions, tasks, and engagement — with built-in business review generation.

Capabilities

Authentication

• Type: OAuth2 (via MCP connector)
• Setup: Connect via Claude MCP connector — no API key management needed
• Scope: All data is scoped to the authenticated organisation

Common Agent Operations

All operations are performed via MCP tools. The following are the primary tool calls available.

Search Partners

search_partners
  dateRange: { field: "CREATED_AT" | "LAST_ACTIVITY_AT", from: "YYYY-MM-DD", to: "YYYY-MM-DD" }

Returns: partner name/ID, contact info, tier, lifecycle stage, categories, country, last activity date.

Search CRM Objects (Deals, Tickets, Leads, Companies, Contacts)

search_crm_objects
  objectType: "DEAL" | "TICKET" | "LEAD" | "COMPANY" | "CONTACT"
  stage: "OPEN" | "WON" | "LOST"
  view: "ALL" | "DUE" | "OVERDUE" | "INACTIVE"
  rollingDateFilter: { field: "CLOSED_AT", value: "THIS_QUARTER" }
  sortBy: { property: "AMOUNT", direction: "DESC" }
  limit: 10

Synonym mapping: Opportunity/Forecast → DEAL, Account → COMPANY, Case → TICKET.

Search Tasks

search_tasks
  status: "TODO" | "IN_PROGRESS" | "PENDING" | "COMPLETED" | "DONE"
  partnerId: "{partner_id}"

Search Commissions

search_commissions
  partnerId: "{partner_id}"

Returns: commission amounts, currency, payment status, associated partner and deals.

Generate Business Review (QBR/MBR/WBR)

generate_business_review
  duration: "QUARTERLY" | "MONTHLY" | "WEEKLY"
  partnerId: "{partner_id}"

Returns: pipeline & forecast analysis, form submissions overview, mutual action plan, goal tracking, timed agenda and next steps.

Search Partner Engagement

search_partner_engagement
  partnerId: "{partner_id}"
  type: "ROOM_VISIT" | "OBJECT_SHARE" | "COMMENT" | "FORM_SUBMIT" | "TASK_CREATED" | ...
  dateRange: { from: "YYYY-MM-DD", to: "YYYY-MM-DD" }

Returns: comments, deal updates, asset views, task events, portal visits, form submissions, announcements, quotes.

Add Comment to Deal/Object

add_comment
  comment: "Comment text"
  objectId: "{crm_object_id}"
  objectType: "DEAL" | "TICKET" | "LEAD" | "COMPANY" | "CONTACT"

Create or Update Tasks

add_task
  name: "Task title"
  dueDate: "2025-02-20"
  assignedTo: "PARTNER" | "ORGANISATION"
  partnerId: "{partner_id}"

update_task
  taskId: 123
  status: "TODO" | "IN_PROGRESS" | "DONE"

Update CRM Object Properties

update_crm_object
  objectId: "{crm_object_id}"
  objectType: "DEAL"
  propertiesToUpdate: { "amount": 50000, "stage": "Negotiation" }

Share Lead or Register Deal

Two-step flow:

1. Discovery: provide objectType and callToAction to get form fields
2. Submit: provide formId and userProvidedData to submit

share_lead_or_register_deal
  objectType: "Deal"
  callToAction: "Register Deal"
  partnerId: "{partner_id}"

Key Metrics

Partner Data

• id - Partner ID
• name - Partner company name
• championEmail - Primary contact email
• tier - Current tier level
• lifecycleStage - Partner lifecycle stage
• categories - Partner categories
• country - Partner country
• lastActivityAt - Last activity date

CRM Object Data

• objectId - External CRM ID
• objectType - DEAL, TICKET, LEAD, COMPANY, CONTACT
• stage - OPEN, WON, LOST
• amount - Deal amount
• closeDate - Expected close date

Commission Data

• amount - Commission amount
• currency - Payment currency
• paymentStatus - Current payment status
• partnerId - Associated partner
• dealId - Associated deal

Engagement Data

• type - Activity type (ROOM_VISIT, COMMENT, FORM_SUBMIT, etc.)
• partnerId - Partner involved
• crmObjectId - Related CRM object
• createdAt - Activity timestamp

When to Use

• Managing channel partner relationships and tracking partner activity
• Reviewing partner-sourced pipeline (deals, leads, opportunities)
• Preparing QBR/MBR/WBR meetings with automated business review generation
• Tracking partner commissions and payouts
• Managing mutual action plans via tasks assigned to partners or internal teams
• Processing deal registrations and lead sharing from partners
• Monitoring partner portal engagement and content asset views

Rate Limits

• Rate limits managed by the MCP connector
• All data scoped to authenticated organisation

Relevant Skills

• revops
• sales-enablement
• referrals
• competitors

---

Supporting file: tools/integrations/mention-me.md

Mention Me

Enterprise referral marketing platform for customer advocacy.

Capabilities

Authentication

• Type: API Key
• Header: Authorization: Bearer {api_key}
• Environment: Separate keys for sandbox and production

Common Agent Operations

Create referral offer

POST https://api.mention-me.com/api/v2/referrer-offer

{
  "email": "customer@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "order_number": "ORD-123",
  "order_total": 99.99,
  "order_currency": "USD"
}

Get referral link for customer

GET https://api.mention-me.com/api/v2/referrer/{customer_id}/share-links

Record referee (referred customer)

POST https://api.mention-me.com/api/v2/referee

{
  "email": "referred@example.com",
  "firstname": "Jane",
  "referrer_code": "JOHN123",
  "order_number": "ORD-456",
  "order_total": 149.99
}

Get referral status

GET https://api.mention-me.com/api/v2/referral/{referral_id}

List referrals for customer

GET https://api.mention-me.com/api/v2/referrer/{customer_id}/referrals

Get reward balance

GET https://api.mention-me.com/api/v2/referrer/{customer_id}/rewards

Redeem reward

POST https://api.mention-me.com/api/v2/referrer/{customer_id}/rewards/redeem

{
  "reward_id": "RWD-123",
  "order_number": "ORD-789"
}

JavaScript Widget

Embed referral widget

<div id="mmWrapper"></div>
<script>
  window.MentionMe = window.MentionMe || [];
  MentionMe.push({
    type: 'offer',
    customer: {
      email: 'customer@example.com',
      firstname: 'John',
      order_number: 'ORD-123'
    }
  });
</script>
<script src="https://tag.mention-me.com/client/{partner_code}.js" async></script>

Name share widget

MentionMe.push({
  type: 'nameShare',
  customer: {
    email: 'customer@example.com'
  }
});

Webhook Events

Key Features

• A/B testing - Built-in experiment framework
• Fraud prevention - Automatic fraud detection
• Multi-channel - Share via link, email, social
• Name sharing - Refer by name, not code
• Segmentation - Different offers by segment
• Analytics - Referral program reporting

Key Objects

• Referrer - Customer who refers
• Referee - Customer who is referred
• Referral - Connection between referrer and referee
• Offer - Referral program configuration
• Reward - Incentive earned

When to Use

• Enterprise referral programs
• Multi-market referral campaigns
• A/B testing referral offers
• Fraud-resistant referral tracking
• Name-based sharing programs

Rate Limits

• 1000 requests per minute
• Contact for higher limits

Relevant Skills

• referrals
• pricing
• analytics

---

Supporting file: tools/integrations/partnerstack.md

PartnerStack

Partner and affiliate program management platform for SaaS companies with deal tracking, rewards, and multi-tier partnerships.

Capabilities

Authentication

• Type: Basic Auth (Vendor API)
• Header: Authorization: Basic {base64(public_key:secret_key)}
• Get credentials: Vendor dashboard > Settings > Integrations > PartnerStack API Keys
• Note: Separate Test and Production API keys. Test transactions can only be added to customers created with Test keys.

Common Agent Operations

List partnerships

GET https://api.partnerstack.com/api/v2/partnerships?limit=25

Authorization: Basic {base64(public_key:secret_key)}

Create a partnership

POST https://api.partnerstack.com/api/v2/partnerships

{
  "email": "partner@example.com",
  "group_key": "affiliates",
  "first_name": "Jane",
  "last_name": "Smith"
}

List customers

GET https://api.partnerstack.com/api/v2/customers?limit=25

Create a customer (attribute to partner)

POST https://api.partnerstack.com/api/v2/customers

{
  "email": "customer@example.com",
  "partner_key": "prtnr_abc123",
  "name": "John Doe"
}

Record a transaction

POST https://api.partnerstack.com/api/v2/transactions

{
  "customer_key": "cust_abc123",
  "amount": 9900,
  "currency": "USD",
  "product_key": "pro_plan"
}

List deals

GET https://api.partnerstack.com/api/v2/deals?limit=25

Create a deal

POST https://api.partnerstack.com/api/v2/deals

{
  "partner_key": "prtnr_abc123",
  "name": "Enterprise Opportunity",
  "amount": 50000,
  "stage": "qualified"
}

Record an action (event-based rewards)

POST https://api.partnerstack.com/api/v2/actions

{
  "customer_key": "cust_abc123",
  "key": "signup_completed",
  "value": 1
}

Create a reward

POST https://api.partnerstack.com/api/v2/rewards

{
  "partner_key": "prtnr_abc123",
  "amount": 5000,
  "description": "Bonus for Q1 performance"
}

List leads

GET https://api.partnerstack.com/api/v2/leads?limit=25

Create a lead

POST https://api.partnerstack.com/api/v2/leads

{
  "partner_key": "prtnr_abc123",
  "email": "lead@company.com",
  "name": "Potential Customer",
  "company": "Acme Corp"
}

List partner groups

GET https://api.partnerstack.com/api/v2/groups

Manage webhooks

POST https://api.partnerstack.com/api/v2/webhooks

{
  "target": "https://example.com/webhooks/partnerstack",
  "events": ["deal.created", "transaction.created", "customer.created"]
}

API Pattern

PartnerStack uses cursor-based pagination. List responses include has_more and item keys for starting_after / ending_before parameters.

All responses follow the format:

{
  "data": { ... },
  "message": "...",
  "status": "2xx"
}

Key Metrics

Partnership Metrics

• partner_key - Unique partner identifier
• group - Partner tier/group
• status - active, pending, archived
• created_at - Partnership start date

Transaction Metrics

• amount - Transaction value in cents
• currency - Currency code
• product_key - Associated product
• customer_key - Associated customer

Deal Metrics

• amount - Deal value
• stage - Deal pipeline stage
• status - open, won, lost

Reward Metrics

• amount - Reward amount in cents
• status - pending, approved, paid

Parameters

Pagination Parameters

• limit - Items per page (1-250, default: 10)
• starting_after - Cursor for next page (item key)
• ending_before - Cursor for previous page (item key)
• order_by - Sort field, prefix with - for descending

Common Filters

• include_archived - Include archived records
• has_sub_id - Filter by sub ID presence

When to Use

• Managing SaaS affiliate and referral programs
• Tracking partner-driven revenue and attributions
• Automating partner onboarding and rewards
• Deal registration and pipeline tracking
• Multi-tier partnership programs (affiliates, resellers, agencies)
• Event-based reward triggers (signups, upgrades, etc.)

Rate Limits

• Not explicitly documented
• Use reasonable request rates; implement exponential backoff on 429 responses

Relevant Skills

• referrals
• affiliate-marketing
• partner-enablement
• saas-metrics
• launch-sequence

---

Supporting file: tools/integrations/rewardful.md

Rewardful

Affiliate and referral tracking for Stripe-based SaaS businesses.

Capabilities

Authentication

• Type: API Key
• Header: Authorization: Bearer {api_secret}
• Get key: Settings > API in Rewardful dashboard

Common Agent Operations

List affiliates

GET https://api.getrewardful.com/v1/affiliates

Get affiliate by ID

GET https://api.getrewardful.com/v1/affiliates/{affiliate_id}

Search affiliate by email

GET https://api.getrewardful.com/v1/affiliates?email=affiliate@example.com

Get referral by Stripe customer

GET https://api.getrewardful.com/v1/referrals?stripe_customer_id={customer_id}

List referrals for affiliate

GET https://api.getrewardful.com/v1/referrals?affiliate_id={affiliate_id}

Get commission details

GET https://api.getrewardful.com/v1/commissions/{commission_id}

List commissions

GET https://api.getrewardful.com/v1/commissions?affiliate_id={affiliate_id}

Create affiliate link

POST https://api.getrewardful.com/v1/affiliates/{affiliate_id}/links

{
  "token": "custom-link-token",
  "url": "https://example.com/pricing"
}

Update affiliate

PUT https://api.getrewardful.com/v1/affiliates/{affiliate_id}

{
  "first_name": "John",
  "last_name": "Doe",
  "paypal_email": "john@example.com"
}

JavaScript Tracking

Install snippet

<script>
(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');
</script>
<script async src='https://r.wdfl.co/rw.js' data-rewardful='YOUR_API_KEY'></script>

Track conversion manually

rewardful('convert', { email: 'customer@example.com' });

Webhook Events

Key Objects

• Affiliate - Partner promoting your product
• Referral - Tracked visit/lead from affiliate
• Commission - Earned payment for affiliate
• Campaign - Program with specific terms
• Link - Tracking URL for affiliate

Integration with Stripe

Rewardful automatically:

1. Tracks referral cookie when user visits via affiliate link
2. Associates Stripe customer with referral on checkout
3. Creates commissions when subscriptions are paid
4. Handles recurring commissions for subscriptions

When to Use

• Setting up affiliate/referral programs for SaaS
• Tracking referral attribution from Stripe payments
• Managing affiliate relationships
• Processing affiliate payouts
• Analyzing referral program performance

Rate Limits

• 120 requests per minute
• Contact support for higher limits

Relevant Skills

• referrals
• pricing

---

Supporting file: tools/integrations/stripe.md

Stripe

Payment processing, subscriptions, and billing for internet businesses.

Capabilities

Authentication

• Type: API Key
• Header: Authorization: Bearer sk_live_xxx or sk_test_xxx
• Keys: Secret key (server), Publishable key (client)

Common Agent Operations

List customers

GET https://api.stripe.com/v1/customers?limit=10

Get customer by email

GET https://api.stripe.com/v1/customers?email=user@example.com

Get subscription

GET https://api.stripe.com/v1/subscriptions/{subscription_id}

List subscriptions for customer

GET https://api.stripe.com/v1/subscriptions?customer={customer_id}

Create checkout session

POST https://api.stripe.com/v1/checkout/sessions

customer={customer_id}
&line_items[0][price]={price_id}
&line_items[0][quantity]=1
&mode=subscription
&success_url=https://example.com/success
&cancel_url=https://example.com/cancel

Create customer portal session

POST https://api.stripe.com/v1/billing_portal/sessions

customer={customer_id}
&return_url=https://example.com/account

List recent invoices

GET https://api.stripe.com/v1/invoices?customer={customer_id}&limit=10

Get payment intent

GET https://api.stripe.com/v1/payment_intents/{payment_intent_id}

Webhook Events

Key events to handle:

Verify webhook signature

const event = stripe.webhooks.constructEvent(
  payload,
  sig,
  webhookSecret
);

CLI Commands

# Listen to webhooks locally
stripe listen --forward-to localhost:3000/webhooks

# Trigger test events
stripe trigger checkout.session.completed

# List recent events
stripe events list --limit 10

# Get resource
stripe customers retrieve cus_xxx

Key Objects

• Customer - User billing profile
• Subscription - Recurring billing
• Price - Pricing configuration
• Product - What you sell
• Invoice - Billing document
• PaymentIntent - One-time payment
• Checkout Session - Hosted payment page

When to Use

• Processing payments
• Managing subscriptions
• Creating checkout flows
• Handling billing portal
• Querying customer data
• Revenue analytics

Rate Limits

• 100 read requests per second
• 100 write requests per second
• Higher limits available on request

Relevant Skills

• pricing
• referrals (Stripe-integrated affiliate tools)
• analytics (revenue tracking)

---

Supporting file: tools/integrations/tolt.md

Tolt

Affiliate program management for SaaS, with Stripe and Paddle integration.

Capabilities

Authentication

• Type: API Key
• Header: Authorization: Bearer {api_key}
• Get key: Settings > API in Tolt dashboard

Common Agent Operations

List affiliates

GET https://api.tolt.io/v1/affiliates

Get affiliate

GET https://api.tolt.io/v1/affiliates/{affiliate_id}

Create affiliate

POST https://api.tolt.io/v1/affiliates

{
  "email": "affiliate@example.com",
  "name": "John Doe"
}

List referrals

GET https://api.tolt.io/v1/referrals?affiliate_id={affiliate_id}

Get referral by customer

GET https://api.tolt.io/v1/referrals?customer_id={stripe_customer_id}

List commissions

GET https://api.tolt.io/v1/commissions?affiliate_id={affiliate_id}

Get payout history

GET https://api.tolt.io/v1/payouts?affiliate_id={affiliate_id}

Update affiliate

PATCH https://api.tolt.io/v1/affiliates/{affiliate_id}

{
  "commission_rate": 30,
  "payout_method": "paypal",
  "paypal_email": "affiliate@paypal.com"
}

JavaScript Tracking

Install snippet

<script src="https://cdn.tolt.io/tolt.js" data-tolt="YOUR_PUBLIC_KEY"></script>

Track signup

window.tolt.signup(stripeCustomerId);

Identify existing customer

window.tolt.identify(stripeCustomerId);

Webhook Events

Key Features

• Stripe native - Automatic commission tracking
• Paddle support - Works with Paddle billing
• Affiliate dashboard - White-labeled portal
• Payout automation - PayPal and Wise payouts
• Custom commission tiers - Different rates per affiliate

Key Objects

• Affiliate - Partner in your program
• Referral - Tracked conversion
• Commission - Earned affiliate payment
• Payout - Processed payment to affiliate
• Program - Campaign configuration

When to Use

• Setting up SaaS affiliate programs
• Managing affiliate relationships
• Tracking Stripe or Paddle-based referrals
• Processing affiliate payouts
• Building affiliate dashboards

Rate Limits

• 100 requests per minute
• Higher limits on enterprise plans

Relevant Skills

• referrals
• pricing