sales-adbutler

What this skill does

# AdButler Platform Help

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

1. **What are you trying to do?**
   - A) Set up AdButler to serve ads on my website or newsletter
   - B) Configure the self-serve portal for advertisers
   - C) Integrate via the REST API or MCP server
   - D) Troubleshoot ad rendering or delivery issues
   - E) Compare AdButler to other ad servers
   - F) Set up programmatic demand (SSP/RTB)

2. **Which side are you on?**
   - A) Publisher (I have a site/newsletter and want ad revenue)
   - B) Advertiser (I want to place ads)
   - C) Developer (building a custom ad platform or integration)

3. **Current setup** (if applicable): channel (web, email, app), monthly ad requests, current ad server

Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.

## Step 2 — Route or answer directly

| If the question is about... | Route to... |
|---|---|
| Newsletter monetization strategy (subscriptions, pricing models) | `/sales-newsletter [question]` |
| Sponsorship marketplace (finding sponsors) | `/sales-paved [question]` or `/sales-hecto [question]` |
| Sponsor intelligence (brands that sponsor newsletters) | `/sales-sponsorgap [question]` |
| Building a custom ad platform from scratch (API-first) | `/sales-kevel [question]` |
| Email deliverability (SPF/DKIM/DMARC) | `/sales-deliverability [question]` |

If the question is AdButler-specific, continue to Step 3.

## Step 3 — AdButler platform reference

**Read `references/platform-guide.md`** for the full platform reference — capabilities, pricing, data model, email ad setup, integration recipes, code examples.

**Read `references/adbutler-api-reference.md`** for API endpoint details, authentication, ad serving JSON API, and MCP server setup.

Answer the user's question using only the relevant section. Don't dump the full reference.

## Step 4 — Actionable guidance

Focus on the user's specific situation:

- **Publisher getting started**: Create a publisher, add zones (email or web), generate zone tags, paste into your template. Start with 1-2 zones, monitor for 2-4 weeks.
- **Email newsletters**: Use email-type zones — image-only ads. Generate zone tag with your ESP's EUID macro. Paste HTML into template. Ads can be updated after send.
- **Self-serve portal**: Enable the self-serve module, configure advertiser registration, set approval workflows and payment processing. Advertisers manage their own campaigns.
- **API integration**: API Access is a paid add-on. Use Bearer token auth against `api.adbutler.com/v2/`. For ad serving, use the JSON API at `servedbyadbutler.com/adserve` (no auth needed).
- **MCP server**: Install with `claude mcp add adbutler -- npx -y @adbutler/mcp-server`. Manage campaigns, pull reports, and automate ad ops through natural language.
- **Choosing AdButler vs alternatives**: AdButler is best for publishers wanting a managed ad server with self-serve portal and email support at $179/mo+. For API-first custom builds, use Kevel. For free/open-source, consider Revive Adserver. For programmatic-only newsletter ads with no setup, use Admailr or Paved.

If you discover a gotcha, workaround, or tip not covered in `references/learnings.md`, append it there.

## Gotchas

> *Best-effort from research — review these, especially items about plan-gated features and integration gotchas that may be outdated.*

1. **API Access is a paid add-on** on all plans — you must add it to your subscription before API keys work. Budget for this if building integrations.
2. **Email zones are image-only** — almost all email clients block Rich Media/Custom HTML ads. Only image creatives work in email zones.
3. **Essentials plan caps at 10 zones and 10 advertisers** — if you need more, you must upgrade to Standard ($682/mo). Check zone/advertiser limits before committing.
4. **Impressions only count on first load** — email ad impressions are recorded when the image loads, but cached images don't re-trigger. Clicks are always tracked.
5. **iOS 15 Mail Privacy Protection** inflates email open counts — MPP pre-fetches images. CPC metrics are more reliable than CPM for email. Regenerate zone tags created before Oct 2021.
6. **Targeting is a paid add-on** — geo, behavioral, and contextual targeting require the targeting add-on on top of your base plan.

## Related skills

- `/sales-newsletter` — Newsletter monetization strategy (paid subscriptions, sponsorships, ad sales, pricing)
- `/sales-kevel` — Kevel API-first ad server infrastructure (build custom ad platforms, Decision API)
- `/sales-admailr` — Admailr programmatic email ad server (automated ad insertion, CPM+CPC, no setup)
- `/sales-paved` — Paved newsletter sponsorship marketplace, Ad Network
- `/sales-buysellads` — BuySellAds contextual advertising marketplace (managed ad sales, Carbon Ads)
- `/sales-passendo` — Passendo email ad server + SSP (programmatic exchange, direct-sold campaigns)
- `/sales-postapex` — PostApex newsletter ad network (500+ publishers, CPC, free for publishers)
- `/sales-hecto` — Hecto newsletter advertising marketplace (self-serve, transparent pricing)
- `/sales-deliverability` — Email deliverability strategy (SPF, DKIM, DMARC, warmup)
- `/sales-do` — Not sure which skill to use? The router matches any sales objective to the right skill. Install: `npx skills add sales-skills/sales --skill sales-do`

## Examples

### Example 1: Publisher setting up email ads
**User says**: "I have a 20K-subscriber newsletter on Mailchimp. How do I add AdButler ads?"
**Skill does**: Walks through creating an email zone, configuring dimensions, adding image ad items, generating the zone tag with Mailchimp's EUID macro (`*|CAMPAIGN_UID|*-*|UNIQID|*`), and pasting the HTML into the Mailchimp template
**Result**: User has AdButler email ads running in their newsletter with click tracking

### Example 2: API integration for reporting
**User says**: "How do I pull campaign performance data from AdButler's API into my dashboard?"
**Skill does**: Shows the Reporting API at `api.adbutler.com/v2/reports` with Bearer auth, required parameters (type, period), response format with impressions/clicks/revenue, and a working cURL + Python example
**Result**: User has working API scripts to pull ad performance data programmatically

### Example 3: Choosing between ad servers
**User says**: "I'm a mid-size publisher with 5M monthly pageviews. Should I use AdButler, Kevel, or Google Ad Manager?"
**Skill does**: Compares all three: AdButler ($230/mo for 5M requests, managed dashboard + self-serve portal, email support), Kevel ($5K+/mo, API-only, requires engineering), GAM (free but complex, Google lock-in). Recommends AdButler for publishers wanting control without building from scratch.
**Result**: User has a clear comparison with pricing and trade-offs for their scale

## Troubleshooting

### Email ads not rendering in some clients
**Symptom**: Ad images appear broken or missing in Outlook, Gmail, or dark mode
**Cause**: Email clients handle image rendering differently; some block remote images by default, dark mode inverts colors
**Solution**: Use only image-type creatives in email zones. Test across clients with Litmus or Email on Acid. For dark mode, avoid transparent backgrounds — use solid backgrounds that work in both light and dark mode. Regenerate zone tags if they were created before the iOS 15 MPP or Outlook image-blocking updates.

### API returns 401 Unauthorized
**Symptom**: Management API calls fail with authentication errors
**Cause**: API Access add-on not enabled, or incorrect auth header format
**Solution**: Verify the API Access add-on is active on your subscription (Settings > Subscription). Use Bearer token: `Authorization: Bearer YOUR_API_KEY`. Optionally whitelist your server IP in Settings > API.

### Self-serve advertisers can't see their campaigns
**Symptom**: Advertisers who signed up through the self-serve portal repo