sales-skills/sales-buttondown

Buttondown Platform Help

Step 1 — Gather context

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

Ask the user:

1. What area of Buttondown do you need help with?

   • A) Writing & sending emails — Markdown editor, scheduling, drafts
   • B) Subscribers — importing, tagging, segments, managing subscribers
   • C) Paid subscriptions — Stripe setup, paywalls, pricing tiers (for strategy, hand off: /sales-newsletter {your question})
   • D) Automations — welcome sequences, tag-triggered flows, surveys
   • E) Custom domains — sending domain, archive hosting
   • F) RSS-to-email — auto-sending from blog posts
   • G) API & CLI — programmatic subscriber/email management
   • H) Integrations — Zapier, Discord, webhooks, Memberful
   • I) Migration — moving from Substack, Mailchimp, Kit, or another platform
   • J) Analytics — open rates, click tracking, subscriber growth
   • K) Account & billing — plans, add-ons, teams, multiple newsletters
   • L) Something else — describe it

2. What plan are you on?

   • A) Free (100 subscribers)
   • B) Basic ($9/mo, 1K subscribers)
   • C) Standard ($29/mo, 5K subscribers)
   • D) Professional ($79/mo, 10K subscribers)
   • E) Advanced or Enterprise
   • F) Not sure

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... | Hand off | |---|---| | Email marketing strategy across tools | "This is an email marketing strategy question — run: /sales-email-marketing {your question}" | | Newsletter monetization strategy | "This is a newsletter monetization question — run: /sales-newsletter {your question}" | | Growing your subscriber list | "This is an audience growth question — run: /sales-audience-growth {your question}" | | Deliverability, SPF/DKIM/DMARC | "This is a deliverability question — run: /sales-deliverability {your question}" | | Connecting Buttondown to other tools | "This is a tool integration question — run: /sales-integration {your question}" |

Answer directly when the question is Buttondown-specific — platform config, UI navigation, API usage, Stripe setup, add-on features.

Step 3 — Buttondown platform reference

Read references/platform-guide.md for the full platform reference — modules, pricing, integrations, data model, workflows.

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

Step 4 — Actionable guidance

You no longer need the platform guide — focus on the user's specific situation.

Provide step-by-step instructions with:

1. Exact navigation — where to click in the Buttondown dashboard
2. Settings to configure — specific fields, values, toggles
3. Plan requirements — flag if a feature requires an add-on or higher plan
4. Verification steps — how to confirm it's working

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. Most features are paid add-ons — tagging, analytics, paid subscriptions, automations, and RSS-to-email each cost $9-$29/mo extra on top of the base plan. Don't assume a feature is available — check which add-ons the user has enabled.

2. Sending limit assumes daily max — pricing is based on sending at most one email per day to your entire subscriber base. If you need higher frequency, contact Buttondown for custom pricing.

3. Automations add-on is $29/mo — unlike Kit or Mailchimp where automations are included, Buttondown charges separately. Welcome sequences require this add-on.

4. API is available on all plans including free — unlike many competitors, even free-tier users can use the full REST API. Auth is Authorization: Token {key} with base URL https://api.buttondown.com/v1/. Manage keys at buttondown.com/keys (API → Keys; granular multiple keys supported). Rate limits: 600 req/min globally; subscriber creation is capped at 100/day (returns 400 — bulk-import larger lists). The create-subscriber body uses email_address (not email).

5. Concierge migration is free — Buttondown migrates your subscriber list from any platform at no cost, usually within one business day. Don't try to do complex migrations manually.

Related skills

• /sales-newsletter — Newsletter monetization strategy (paid subscriptions, sponsorships, premium tiers)
• /sales-email-marketing — Cross-platform email marketing strategy (broadcasts, automation, segmentation)
• /sales-audience-growth — Audience growth strategy (lead magnets, cross-promotion, referral programs)
• /sales-deliverability — Cross-platform deliverability (SPF/DKIM/DMARC, warmup, inbox placement)
• /sales-kit — Kit (formerly ConvertKit) platform help — direct competitor
• /sales-ghost — Ghost platform help — newsletter + publishing alternative
• /sales-mailerlite — MailerLite platform help — affordable newsletter alternative
• /sales-digital-products — Selling digital products alongside your newsletter
• /sales-integration — Connect Buttondown to CRM and other tools via API, Zapier, webhooks
• /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: Setting up paid subscriptions

User says: "How do I charge for my newsletter on Buttondown?" Skill does: Walks through enabling the Paid Subscriptions add-on, connecting Stripe, configuring pricing tiers, and setting up paywalled content with the paywall toggle Result: User has a working paid newsletter with Stripe payments

Example 2: Migrating from Substack

User says: "I want to move my 2,000 subscribers from Substack to Buttondown" Skill does: Recommends using Buttondown's free concierge migration service, explains what transfers (subscribers, archives), flags what doesn't (Substack-specific features like Notes), and covers domain authentication setup Result: User has a migration plan with zero subscriber loss

Example 3: API integration

User says: "I want to automatically add subscribers from my app to Buttondown" Skill does: Provides the POST /v1/subscribers endpoint with auth header, request body format, and example cURL/Python code. Covers tag assignment and metadata fields Result: User has working API integration code

Troubleshooting

Paid subscriptions not collecting payment

Symptom: Paywall is enabled but readers can't pay or see no payment option Cause: Stripe not connected, or Paid Subscriptions add-on not enabled Solution: Go to Settings → Paid Subscriptions, verify the add-on is active ($9/mo), and check Stripe connection status. Test with a Stripe test-mode payment. Ensure the email has the paywall toggle enabled.

Emails stuck in draft or not sending

Symptom: Email shows as draft but won't send, or scheduled send didn't fire Cause: Email may be flagged by Buttondown's built-in checks (broken links, malformed images), or sending domain not verified Solution: Check the email's status page for warnings. Verify your sending domain in Settings → Domains. If using a custom domain, confirm DNS records (SPF/DKIM) are propagated.

Subscribers not appearing after import

Symptom: Imported a CSV but subscriber count didn't change Cause: CSV format issues, duplicate emails, or import still processing Solution: Check import status in Subscribers → Imports. Verify CSV has a column header named "email" (case-sensitive). Duplicates are silently skipped. Large imports may take several minutes.