Buttondown Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Ask the user:
- 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
- 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:
- Exact navigation — where to click in the Buttondown dashboard
- Settings to configure — specific fields, values, toggles
- Plan requirements — flag if a feature requires an add-on or higher plan
- 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.*
- 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.
- 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.
- Automations add-on is $29/mo — unlike Kit or Mailchimp where automations are included, Buttondown charges separately. Welcome sequences require this add-on.
- 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 URLhttps://api.buttondown.com/v1/. - 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.