Buttondown Platform Help
Step 1 — Gather context
If
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
, 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 URL
https://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
- — Newsletter monetization strategy (paid subscriptions, sponsorships, premium tiers)
- — Cross-platform email marketing strategy (broadcasts, automation, segmentation)
- — Audience growth strategy (lead magnets, cross-promotion, referral programs)
- — Cross-platform deliverability (SPF/DKIM/DMARC, warmup, inbox placement)
- — Kit (formerly ConvertKit) platform help — direct competitor
- — Ghost platform help — newsletter + publishing alternative
- — MailerLite platform help — affordable newsletter alternative
- — Selling digital products alongside your newsletter
- — Connect Buttondown to CRM and other tools via API, Zapier, webhooks
- — 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.