Mattering Automations Buttondown integration
Connect Buttondown to Mattering Automations: subscribers, emails, tags, segments, forms, imports, automations, RSS-to-email feeds, events, analytics, webhooks, surveys, comments and sponsorship inventory as workflow steps, authenticated with one API key.
The Mattering Automations Buttondown integration puts Buttondown's v1 API on your automation canvas, pinned to API version 2026-04-01: read and write subscribers, draft and publish emails, manage tags, segments, forms and snippets, drive imports and exports, run and inspect automations and RSS-to-email feeds, read events and per-email analytics, register and test webhooks, work surveys and comments, and manage newsletters, team members, prices and sponsorship inventory. 126 nodes in total, 60 that read and 66 that act.
The credential is a single API key. Buttondown sends it in an Authorization header prefixed with the literal word Token rather than Bearer, which is the single easiest thing to get wrong against this API because the failure is a clean 401 that reads like a bad key. This integration writes the prefix for you, so you paste the bare key, and it strips a pasted Token or Bearer prefix rather than failing on it. Keys also carry independent permissions across eight areas of the API, so a key can be issued that reads subscribers and cannot send anything.
Two things are worth reading before you build. First, nine of these nodes put mail in real inboxes and cannot be recalled, and Buttondown's own API defaults a newly created email into a sending status, so Buttondown: Create Email deliberately defaults to draft instead. Second, the API is free on every Buttondown plan including the free one, but Buttondown sells much of the product as add-ons, so a free key authenticates perfectly and then returns 403 or an empty list against tags, comments, surveys, analytics, automations, RSS-to-email, sponsorships, attachments, paid subscriptions and teams. Both are explained in full below, and this guide ends with the complete node reference.
Before you start
- A Buttondown account. The API is available on every plan including the free one, and there is no API add-on to purchase.
- An API key created in the API section of your Buttondown settings, under Keys. You can create as many as you need, so a key labelled for this integration is better than reusing your account's primary key, which always carries full access and cannot be scoped or deleted.
- A decision about that key's permissions. Buttondown sets them independently for subscribers, emails, sending, newsletter settings, automations, forms, design settings and surveys, each as write, read or none. Read is enough for the 60 query nodes. Sending access is what the nine nodes that mail people need, and withholding it is a genuine safety control rather than an inconvenience.
- An awareness of which families your plan includes. Buttondown's pricing page lists its add-ons by name, and several of them are whole object families in this integration: tagging and segmentation, comments and surveys, analytics, automations, RSS-to-email support, sponsorships, email attachments, paid subscriptions, teams, and running more than one newsletter. A free account authenticates fine and then gets a 403 or an empty list on those, which looks like a broken connector and is not one. Check Buttondown's pricing page for what your tier includes before building on one of them.
- A newsletter to test against, ideally one with Buttondown's test_mode setting turned on. With it on, Buttondown redirects every email to the newsletter's own primary address instead of delivering it to subscribers, which is the closest thing to a sandbox for the nine nodes that send. Both Buttondown: Create Newsletter and Buttondown: Update Newsletter expose the setting, and running more than one newsletter is itself a paid feature.
- A Mattering workspace with access to the Automations app.
Create a Buttondown API key
Buttondown authenticates with one API key and nothing else. The decision that carries weight is the key's permissions, because they are set on the key rather than requested at connect time, and an operation outside them returns 403 rather than 401. Decide what this integration is allowed to do before you paste anything.
Connect Buttondown to Mattering
Verify it works
Open any automation canvas and check the palette: a Buttondown section should list the read and action nodes. Drop Buttondown: Ping on the canvas and run a test step. It is the integration's natural probe because it takes no configuration at all and returns an empty object on success, which makes it the first thing to run whenever a Buttondown node starts failing.
Now run Buttondown: Get Account, which returns the username and email address behind the key. This is the step that answers which Buttondown account a stored credential actually belongs to, and it is worth doing before anything writes, especially if your organisation holds credentials for more than one newsletter.
Run Buttondown: List Subscribers without changing anything and read what comes back. This is the richest query surface in the API and every one of its 48 parameters is typed on the node, so it is also the best place to see the filtering conventions: range filters use the __start and __end suffixes and are inclusive at both ends, and Buttondown's negated filters, which it spells with a leading hyphen, appear here as exclude_type, exclude_tag and exclude_domain and are renamed on the wire.
If your account runs more than one newsletter, open the Newsletter Context picker on any node and confirm it populates. It is sourced from Buttondown: List Newsletters and appears on 116 of the 126 nodes; on an ordinary single-newsletter account you leave it blank. Everything in this verify path is read-only, so it cannot reach any node that sends or deletes and is safe to re-run whenever you want to check the connection.
Node reference
126 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 60
Buttondown: Get API Request
buttondown_get_api_request
Get one logged API request in full, including the raw request body and the request headers. Buttondown retains the RESPONSE body only for requests that carried an X-Idempotency-Key, which is a real reason to set one on the create nodes: without a key there is no stored response to inspect when a duplicate turns up. Buttondown redacts UUIDs inside header values, and this connector additionally blanks any authorization header before the response leaves.
Buttondown: Get Account
buttondown_get_account
Get the account behind the API key: its username and email address. Use it to confirm which Buttondown account a stored credential belongs to before a workflow writes anything, which matters most when an organisation holds credentials for several newsletters.
Buttondown: Get Attachment
buttondown_get_attachment
Get one attachment with its name, hosted file URL and size in bytes. The file URL is a real link to the stored file, so treat it as you would any other link to private content.
Buttondown: Get Automation
buttondown_get_automation
Get one automation with its trigger, status, filters and resolved action list, including each action's timing. Read it before updating: the update node replaces the whole actions list rather than merging into it.
Buttondown: Get Automation Analytics
buttondown_get_automation_analytics
Get one automation's aggregate performance in the same shape as an email's: recipients, deliveries, opens, clicks, failures with per-reason breakdowns, unsubscriptions, complaints, replies and attributed subscriptions. These are lifetime totals for the automation rather than a time series, so they are a snapshot to compare against another snapshot, not something to add up. Analytics are a paid Buttondown feature.
Buttondown: Get Bulk Action
buttondown_get_bulk_action
Get one bulk action's status and the parameters it was created with. Statuses are not_started, in_progress, processed and failed. Poll this after Buttondown: Create Bulk Action, because the work happens in the background and the create call returns before any of it has been done. There is no lister for bulk actions in this API, so hold the id the create node returned.
Buttondown: Get Comment
buttondown_get_comment
Get one comment with its text, moderation status, the email it belongs to and when it was posted.
Buttondown: Get Email
buttondown_get_email
Get one email with its full body, audience filters, archive URL, status and, once it has been sent, its analytics block. The analytics here are the same numbers Buttondown: Get Email Analytics returns, so a workflow that already needs the body does not need the second call.
Buttondown: Get Email Analytics
buttondown_get_email_analytics
Get one email's performance: recipients, deliveries, unique opens, unique clicks, temporary and permanent failures with a per-reason breakdown of each, unsubscriptions, complaints, replies, comments, survey responses, webmentions, social mentions, archive page views over lifetime and the last 30 and 7 days, and the subscriptions and paid subscriptions attributed to the issue. These are lifetime-to-date counters for one email rather than a time series, so they are a snapshot and must never be added together across snapshots. Analytics are a paid Buttondown feature.
Buttondown: Get Email History Entry
buttondown_get_email_history_entry
Get the FULL stored value of one history entry. The listing endpoint is fine for a subject line but truncates nothing useful about a body; this is where you fetch a complete previous draft, for a diff or for a restore workflow that writes the old value back with Buttondown: Update Email.
Buttondown: Get Email Render
buttondown_get_email_render
Render an email to finished HTML without sending anything. The target parameter is required and picks which rendering you get: 'email' returns the version that would be mailed, with the template and inlined styling applied, and 'html' returns the version that would appear on the web archive. Use it for an approval step, a preview in another tool, or an automated check that a template change did not break the layout.
Buttondown: Get Event
buttondown_get_event
Get one event with its type, timestamp and type-specific metadata, such as the URL behind a click or the reason behind a bounce. Expand subscriber or email to resolve the references in the same call.
Buttondown: Get Export
buttondown_get_export
Get one export's status and collections. Poll it after Buttondown: Create Export until the status is ready, then collect the files from Buttondown itself. Statuses are not_started, in_progress, ready and error.
Buttondown: Get External Feed
buttondown_get_external_feed
Get one RSS feed with its URL, status, behaviour, cadence and scheduling metadata, audience filters and the subject and body templates it renders items with.
Buttondown: Get Form
buttondown_get_form
Get one form with its title, slug, body and success copy, custom CSS, attached tags and surveys, admin flag, status, and its page view, subscriber and confirmed-subscriber counts.
Buttondown: Get Import
buttondown_get_import
Get one subscriber import with its status, type and detected source. Poll this after starting an import: the work happens in the background and the status is the only thing that says whether it validated, succeeded or failed.
Buttondown: Get Newsletter
buttondown_get_newsletter
Get one newsletter's full settings: sending identity, custom domains and their verification status, theme and template, timezone and locale, header and footer, custom CSS, enabled features, every custom lifecycle email body and subject, and the test-mode flag. The api_key field on this object is a live credential and is blanked by this connector before the response leaves.
Buttondown: Get Newsletter Hosting Domain
buttondown_get_newsletter_hosting_domain
Check the DNS state of a newsletter's custom ARCHIVE hosting domain: the record type Buttondown expects, the values currently observed at the domain, the nameservers, and the verification status. Use it as a monitor, because an archive domain that quietly stops resolving takes every link in every past issue with it.
Buttondown: Get Newsletter Sending Domain
buttondown_get_newsletter_sending_domain
Check the DNS verification state of a newsletter's custom SENDING domain. Returns each required record with its own verification state, plus human-readable warnings about misconfiguration such as a record left proxied through Cloudflare, and a note when another mail provider already holds the domain's MX record. Set force to trigger a fresh check instead of reading the last known result; is_checking comes back true while that runs, so poll until it clears.
Buttondown: Get Segment
buttondown_get_segment
Get one segment with its name, description and complete filter tree. To see who is actually in it, take the filters and run Buttondown: List Subscribers with the equivalent tag and type parameters: this API has no members endpoint on a segment.
Buttondown: Get Snippet
buttondown_get_snippet
Get one snippet with its identifier, name, content and mode. To find which emails depend on it, pass its id to Buttondown: List Emails as snippet_id.
Buttondown: Get Subscriber
buttondown_get_subscriber
Get one subscriber by id OR by email address. The email route is the useful half: a workflow holding only an address can read the record without listing and filtering first, and the address is URL encoded for you. Returns lifecycle type, tags, metadata, signup attribution, and lifetime-to-date engagement counters with their derived open and click rates.
Buttondown: Get Survey
buttondown_get_survey
Get one survey with its question, ordered answer choices, total response count, cadence, input type and status. Read it before interpreting responses: a response records its answer by position in this list.
Buttondown: Get Tag
buttondown_get_tag
Get one tag with its name, colour, both descriptions, subscriber-editable flag and human-readable secondary id.
Buttondown: Get Tag Analytics
buttondown_get_tag_analytics
Get engagement for one tag: how many subscribers were created carrying it, and the open and click rates of emails sent to subscribers who have it. Three numbers, no window and no breakdown, so it answers 'is this segment worth mailing' rather than 'how did this segment behave in August'. The two rates are rates, so comparing them across tags is fair and adding them is not.
Buttondown: Get User
buttondown_get_user
Get one team member with their email address, invitation status, last login and full per-resource permissions. Read it before updating, because the update node takes a complete permissions object rather than a delta.
Buttondown: Get Webhook
buttondown_get_webhook
Get one webhook with its URL, status, subscribed event types and description. The signing key is blanked by this connector before the response leaves.
Buttondown: List API Requests
buttondown_list_api_requests
Read Buttondown's own log of API calls made against the newsletter: method, path, status code, source, the API version that served it, the calling IP and which key was used. Filter by status code to find failures, or by version to see what is still calling an old one. TWO THINGS DIFFER FROM EVERY OTHER LISTER HERE. It is cursor-paginated rather than page-numbered, returning results and a cursor with no count and no next URL, and Buttondown documents no parameter for sending the cursor back, so page two is not reachable from the documented surface: narrow with the date filters instead. And it takes limit rather than page_size.
Buttondown: List Advertising Slots
buttondown_list_advertising_slots
List every sponsorship slot across all units, with its date, status, sponsor contact details, submitted ad content and approval state, the sponsor's own submission URL and a link to the Stripe invoice. Statuses are open, held, sold, finalized, executed and expired. This is the node a sponsor pipeline polls: find sold slots whose content has been submitted but not approved, and route them for review.
Buttondown: List Advertising Units
buttondown_list_advertising_units
List sponsorship inventory: each advertising unit with its title, price in the smallest currency unit, whether it accepts HTML or an image, its character limit, its submission deadline in days, and its dated slots. This is the node a sponsor-pipeline workflow starts from. Sponsorships are a paid Buttondown feature.
Buttondown: List Attachments
buttondown_list_attachments
List file attachments with each one's name, hosted file URL and size in bytes. Their ids are what Buttondown: Create Email and Buttondown: Update Email take in their attachments list. Uploading is a file upload done in Buttondown itself. Attachments are a paid Buttondown feature.
Buttondown: List Automations
buttondown_list_automations
List the newsletter's automations with their trigger event, status, audience filters and the ordered list of actions each one performs. This is the inventory node: it answers what fires on a subscriber event, which is the first thing to check when Buttondown sends something nobody expected. Automations are a paid Buttondown feature.
Buttondown: List Comments
buttondown_list_comments
List comments left on emails, filtered by email, subscriber, parent comment or moderation status. Filtering by status is owner-only, which is what makes a moderation queue possible: pull the pending ones, decide, and act with Buttondown: Update Comment. Expand subscriber and email to avoid a second call per row. Comments are a paid Buttondown feature.
Buttondown: List Coupons
buttondown_list_coupons
List the Stripe coupons available to the newsletter, with each one's id, display name and discount as either a percent or a fixed amount off in the smallest currency unit. Read only: coupons are created in Stripe, not here. Their ids are what Buttondown: List Subscribers takes in its coupon filter.
Buttondown: List Email History
buttondown_list_email_history
List the revision history of ONE FIELD on an email. The field parameter is required and names which field to trace, which is why this is a history of a field rather than a history of the email. Each entry carries a monotonically increasing history_id, the value at that point, and who changed it. Expand user to get the person rather than a bare id.
Buttondown: List Emails
buttondown_list_emails
List and filter emails: drafts, scheduled issues, sent issues and everything between. Filter by status, source, archival mode, subject substring, attachments, referenced snippets, and by TWO independent date windows, one on creation and one on publication. Performance ranges filter on deliveries, open rate and click rate, which is how you find the issues worth reading closely. Every row carries its own analytics block once the email has been sent. Use excluded_fields to drop body from a large listing, which is the single biggest thing you can do to make this call fast.
Buttondown: List Events
buttondown_list_events
List delivery and engagement events: delivered, opened, clicked, bounced, complained, rejected, replied and unsubscribed. Each event carries type-specific metadata, such as the clicked URL or the bounce reason. Filter by event type, email, automation or subscriber, and expand subscriber or email to get whole objects inline. THIS ENDPOINT HAS NO DATE FILTER: Buttondown documents no creation-date range here, so an incremental sync has to page from the newest end and stop when it recognises an event it has already seen. Page size defaults to 500 and goes to 5000, which is the highest ceiling anywhere in this API and is what makes that workable.
Buttondown: List Exports
buttondown_list_exports
List data exports with the collections each one covers and its status: not_started, in_progress, ready or error. Use it to find a recent export rather than creating another, which matters because an export of a large newsletter is not cheap to produce.
Buttondown: List External Feed Items
buttondown_list_external_feed_items
List the items Buttondown has discovered in one feed, with each item's title, URL, author, parsed content, publish date and processing status, plus the id of the email generated from it. Statuses are unprocessed, queued, processed, skipped, irrelevant and errored, so this is where you find out why a blog post never became an issue. Expand email to get the whole generated email inline.
Buttondown: List External Feeds
buttondown_list_external_feeds
List the RSS-to-email feeds configured on the newsletter, with each feed's source URL, polling cadence, behaviour, subject and body templates and audience filters. The behaviour is the field to read first: draft turns new items into drafts for review, while emails turns them into sent issues without anybody looking.
Buttondown: List Forms
buttondown_list_forms
List Buttondown's hosted signup forms with their titles, slugs, attached tags and surveys, status, and three counters: page views, signups and CONFIRMED signups. The gap between the last two is the double opt-in drop-off, which is the number worth watching per form.
Buttondown: List Images
buttondown_list_images
List images uploaded to the newsletter, with each one's hosted URL and metadata. Use it to find the URL of an image to drop into an email body, or to audit what is stored. Uploading is a file upload and is done in Buttondown itself; this connector reads and manages images rather than creating them.
Buttondown: List Imports
buttondown_list_imports
List subscriber imports with each one's status and detected source. Buttondown recognises the export shape of a number of other tools and names which one it detected: substack, mailchimp, ghost, beehiiv, mailerlite, flodesk, tinyletter, sendy, squarespace, shopify, memberful, sparkloop, pencilbooth, sender_dot_net, google and buttondown itself, plus bare, standard and custom for unrecognised files. Statuses are not_started, validating, in_progress, succeeded and failed, so this is the node a migration workflow polls.
Buttondown: List Newsletters
buttondown_list_newsletters
List the newsletters this API key can reach, with each one's name, username, description, sending identity, custom domain status, theme and enabled features. On an ordinary account this returns exactly one row and is the cheapest way to prove a credential works. On a platform account it returns every newsletter, and its ids are what the newsletter_context field on every other node picks from. The newsletter object carries an api_key field; this connector blanks it before the response leaves, because it is a live credential.
Buttondown: List Notes
buttondown_list_notes
List internal notes, optionally scoped to one object. Notes are private annotations attached to a subscriber, an email, an automation, a comment or several other object types, and they are never visible to subscribers. Pass both model_type and model_id to read the notes on one record. Expand user to see who wrote each one.
Buttondown: List Prices
buttondown_list_prices
List the newsletter's paid-subscription prices with each one's amount in the smallest currency unit, currency, billing cadence and style. Styles are fixed, pay-what-you-want (which uses the minimum, maximum and suggested amounts) and usage-based. Expand product to inline the Stripe product. Paid subscriptions need Stripe connected to the newsletter.
Buttondown: List Segments
buttondown_list_segments
List the newsletter's saved segments with their names, descriptions and filter rules. A segment is a named audience definition rather than a stored list of people, so it re-evaluates every time it is used and never goes stale.
Buttondown: List Snippets
buttondown_list_snippets
List reusable content snippets with their identifiers, names, content and editor mode. A snippet is referenced inside an email body as {{ snippets.<identifier> }}, so the identifier matters more than the name: it is the string emails are written against.
Buttondown: List Subscriber Automations
buttondown_list_subscriber_automations
List the automation attempts queued or already run for one subscriber, with each attempt's status, scheduled execution time and resolved actions. This is how you answer 'what is about to be sent to this person', which the automation definition alone cannot tell you. Automations are a paid Buttondown feature.
Buttondown: List Subscriber Referrals
buttondown_list_subscriber_referrals
List the subscribers one person has referred. Returns full subscriber objects, so a rewards workflow can count confirmed referrals rather than raw signups by filtering the returned rows on type.
Buttondown: List Subscriber Stripe Subscriptions
buttondown_list_subscriber_stripe_subscriptions
List one subscriber's Stripe subscriptions: amount, currency, cadence, Stripe status, start and end dates, the product name, and a deep link into the Stripe dashboard. Returns nothing on a newsletter without paid subscriptions connected.
Buttondown: List Subscribers
buttondown_list_subscribers
List and filter subscribers. This is the richest query surface in the API: Buttondown accepts 48 parameters here and every one of them is typed on this node. Filter by lifecycle type, tag, email domain, signup source, form, import, referral code, UTM values, Stripe price or coupon, and by eleven separate date ranges covering creation, churn, bounce, last open, last click, undeliverability, unsubscription and upgrade. Numeric ranges cover open rate, click rate and firewall risk score. Range filters use the __start and __end suffixes and are inclusive at both ends. Buttondown spells its negated filters with a leading hyphen, which makes a poor field name, so they appear here as exclude_type, exclude_tag and exclude_domain and are renamed on the wire.
Buttondown: List Survey Responses
buttondown_list_survey_responses
List survey responses, filtered by survey, subscriber, the email or automation they were submitted from, an arbitrary source string, or a creation date window. Each response carries the chosen answer and any freeform text. Expand subscriber and survey to get whole objects instead of ids, which is what turns a response feed into something a workflow can act on without three more calls.
Buttondown: List Surveys
buttondown_list_surveys
List surveys with their questions, answer choices, response counts, input type and status. Order by response_count to see which questions readers actually answer. Surveys are a paid Buttondown feature; a free newsletter gets an empty list.
Buttondown: List Tags
buttondown_list_tags
List the newsletter's tags with their names, colours, internal and public descriptions, and whether subscribers can apply them to themselves from the portal. Tags are how Buttondown segments an audience, so this is the node the tag picker on every other node reads from. Tags are a paid Buttondown feature; a free newsletter gets an empty list.
Buttondown: List Users
buttondown_list_users
List the team members on the newsletter with each one's email address, invitation status, last login and per-resource permissions. Statuses are pending, accepted, declined, revoked and owner. Use it as an access review: a quarterly workflow that lists users and posts anybody still pending or long dormant is a cheap security control.
Buttondown: List Webhook Attempts
buttondown_list_webhook_attempts
List delivery attempts for one webhook, with each attempt's status, event type, retry count, duration in milliseconds and, on a failure, an error message carrying the response status code and a snippet of the response body. This is the node that tells you whether the integration is silently broken: filter on failed and alert when the count moves.
Buttondown: List Webhooks
buttondown_list_webhooks
List the newsletter's webhooks with their target URL, status and subscribed event types. The signing key each one carries is blanked by this connector before the response leaves, because it is the secret that proves a delivery came from Buttondown and it has no business travelling through a workflow.
Buttondown: Ping
buttondown_ping
Check that Buttondown is reachable and that the API key is accepted. It takes no configuration at all and returns an empty object on success, which makes it the cheapest possible health check inside a workflow and the first thing to run when a Buttondown node starts failing. It proves the key is valid; it does not prove the key has the per-resource permissions a particular node needs, because Buttondown answers that with a 403 on the node itself.
Buttondown: Search Public Emails
buttondown_search_public_emails
Search the PUBLIC archive of any Buttondown newsletter by its username, returning the emails visible on buttondown.com rather than everything in the account. It addresses a newsletter by its public handle, so it works against newsletters the credential does not own, which makes it useful for building a search box over your own archive and for reading a newsletter you follow. Nothing private is reachable through it.
Action nodes 66
Buttondown: API Request
buttondown_api_request
Call any Buttondown endpoint directly. The escape hatch for an operation this connector does not ship as its own node and for anything Buttondown adds between rebuilds. It inherits everything the typed nodes get: the Token authorization header, the pinned X-API-Version, the optional newsletter context, the idempotency key and the response scrubbing that blanks API keys and signing keys. FLAGGED DESTRUCTIVE BECAUSE THE METHOD IS YOURS TO CHOOSE: this node will happily DELETE a newsletter. It cannot do file uploads, because those are multipart form posts rather than JSON. Prefer a typed node whenever one exists; they carry the validation, the warnings and the sample output that this one cannot.
Buttondown: Create Advertising Unit
buttondown_create_advertising_unit
Create a sponsorship unit: a kind of ad slot a sponsor can buy. Only the title is required. The price is IN THE SMALLEST CURRENCY UNIT, so 25000 is two hundred and fifty dollars. Submission deadline days is how far ahead of a slot's date a sponsor must have supplied their content. Sponsorships are a paid Buttondown feature.
Buttondown: Create Automation
buttondown_create_automation
Create an automation: a trigger event, an optional audience filter, and an ordered list of actions. Creating it does not send anything, but it arms something that will, so review the trigger before saving. Triggers are Buttondown's external event names such as subscriber.confirmed, subscriber.paid, subscriber.unsubscribed, email.sent or the date.* calendar events. Actions include send_email, add_tags, remove_tags, add_metadata, unsubscribe_subscriber, send_post_request and the social-posting family, each with its own metadata object and an optional delay.
Buttondown: Create Bulk Action
buttondown_create_bulk_action
Run one operation across many records at once. This is the most powerful node in the connector and the easiest one to cause damage with, because the TYPE decides everything and several of the 34 types are irreversible: delete_subscribers, delete_emails, delete_comments, delete_surveys, delete_survey_responses, delete_tags, delete_attachments and delete_images all destroy data, ban_subscribers and unsubscribe_subscribers change people's status in bulk, send_emails IS A MASS SEND, and the cancel_stripe_subscriptions and modify_stripe_subscriptions types reach into billing. It also does the useful safe work: apply_tags, add_notes, apply_metadata and rename_metadata across a filtered set. Runs in the background; poll Buttondown: Get Bulk Action for the outcome. It is also the right answer to the 100-a-day subscriber create limit for operations over existing subscribers.
Buttondown: Create Comment
buttondown_create_comment
Post a comment on an email, or a reply to another comment. Text is required and one of email_id or parent_id must be given. Leaving subscriber_id blank attributes the comment to the newsletter owner, which is how an author replies to readers from a workflow; setting it attributes the comment to that subscriber, so use it only when they actually said it. Comments are a paid Buttondown feature.
Buttondown: Create Email
buttondown_create_email
Create an email. READ THE STATUS FIELD BEFORE USING THIS NODE. Buttondown's own default status for a newly created email is about_to_send, which means a bare create SENDS the email to the whole audience and cannot be recalled. This node defaults status to draft instead, so the safe thing happens unless somebody deliberately asks for the other thing. Body accepts Markdown or HTML and Buttondown detects which. The filters object narrows the audience by tag or metadata; leave it out to mail everyone. Publish date in the future with status scheduled is how you queue an issue.
Buttondown: Create Export
buttondown_create_export
Start a data export. Collections is required and names what to export: subscribers, emails, events, referrals, surveys, comments, requests, mentions, conversations, images and the Stripe collections. The export runs in the BACKGROUND, so this node returns an id and a status rather than data; poll Buttondown: Get Export until status is ready. This is the node to run before anything destructive, and the export itself changes nothing.
Buttondown: Create External Feed
buttondown_create_external_feed
Create an RSS-to-email feed. Buttondown requires six fields here: the feed URL, the behaviour, the cadence, the audience filters, and the subject and body templates that turn a feed item into an issue. CHOOSE THE BEHAVIOUR DELIBERATELY: draft creates a draft per item and waits for a human, while emails sends each item to subscribers automatically. Set skip_old_items unless you want the whole back catalogue processed the first time the feed is polled.
Buttondown: Create Form
buttondown_create_form
Create a hosted signup form. Title and slug are required and the slug becomes the form's public URL. Attach tags to have every signup arrive already segmented, and attach surveys to ask a question at signup. THE admin FLAG IS THE ONE TO THINK ABOUT: an admin form skips double opt-in confirmation, which is right for an internal back-office form and wrong for anything a stranger can reach.
Buttondown: Create Newsletter
buttondown_create_newsletter
Create a newsletter. Buttondown requires a name, a username and a description; the username is the URL-safe identifier that becomes buttondown.com/<username>, so it is effectively permanent once anybody has linked to the archive. Running more than one newsletter on an account is a paid Buttondown feature. Set test_mode to true on a newsletter you intend to use as a sandbox: with it on, Buttondown redirects every email to the newsletter's own primary address instead of sending it to subscribers, which is the only safe way to exercise the nine sending nodes in this connector.
Buttondown: Create Note
buttondown_create_note
Attach an internal note to any Buttondown object. All three of body, model_type and model_id are required. This is the node that writes context back from another system: a support ticket reference on a subscriber, a review decision on an email, a reason on a comment. Notes are never shown to subscribers.
Buttondown: Create Price
buttondown_create_price
Create a paid-subscription price. Cadence, currency and style are required. AMOUNTS ARE IN THE SMALLEST CURRENCY UNIT, so 500 is five dollars and not five hundred: getting this wrong is a hundredfold pricing error that reaches real customers. For a pay-what-you-want price, set style accordingly and use the minimum, maximum and suggested amounts instead of a fixed one.
Buttondown: Create Segment
buttondown_create_segment
Create a saved segment from a set of tag and metadata filters. Both the name and the filters are required. Use it to give a recurring audience a name once instead of rebuilding the same filter object on every email, which also means correcting the definition later corrects every email that uses it.
Buttondown: Create Snippet
buttondown_create_snippet
Create a reusable snippet. The identifier is a newsletter-scoped slug and is how emails reference it, as {{ snippets.<identifier> }}. Mode decides how content is interpreted: fancy is rich text stored as HTML, naked is raw HTML passed through, plaintext is escaped. Good for a sponsor block, a standard footer or a call to action that several issues share.
Buttondown: Create Subscriber
buttondown_create_subscriber
Add a subscriber. THE RATE LIMIT ON THIS ONE ENDPOINT IS 100 REQUESTS PER DAY, against 600 per minute everywhere else in the API, and Buttondown's own guidance is that a migration or backfill should not go through here at all. Use the Imports surface or Buttondown: Create Bulk Action for anything bigger than a trickle of live signups. Collision behaviour is a header rather than a body field: no_op returns the existing subscriber untouched (the default), overwrite replaces it, and errors fails loudly. Tags are passed by NAME and are created if they do not exist.
Buttondown: Create Survey
buttondown_create_survey
Create a survey. Identifier, question and answers are all required. The identifier is the slug emails embed the survey by, so it is the string content is written against. Response cadence is once (one response per subscriber, the default) or once_per_email. Turning on freeform responses adds a text box beside the choices, which is where the useful answers usually come from. Surveys are a paid Buttondown feature.
Buttondown: Create Survey Response
buttondown_create_survey_response
Record a survey response on a subscriber's behalf, which is how an answer collected somewhere else (a landing page, a support conversation, another form tool) gets into Buttondown. All four fields are required. THE ANSWER IS A NUMBER, not text: it is the 1-based position of the choice in the survey's own answers list, so read the survey first and do not assume the order is stable.
Buttondown: Create Tag
buttondown_create_tag
Create a tag. Both name and colour are required by Buttondown, and the colour is a hex code. Collision behaviour is a header rather than a body field: no_op returns the existing tag when the name is taken, overwrite replaces it. Setting subscriber_editable lets readers add and remove the tag themselves from the subscriber portal, which is how self-service preference centres are built. Tags are a paid Buttondown feature.
Buttondown: Create User
buttondown_create_user
Invite a team member and set what they may do. Both the email address and the permissions object are required. It emails an invitation to the address given, so it is not a silent write, and revoking access afterwards means deleting the user. Permissions are per resource, exactly like the API key scopes: subscriber, email, sending, styling, administrivia, automations, surveys and forms, each write, read or none, with anything left out defaulting to none. Grant sending only to people who should be able to mail the list.
Buttondown: Create Webhook
buttondown_create_webhook
Create a webhook so Buttondown POSTs to a URL you own whenever one of the chosen events happens. Set a signing key and Buttondown signs every delivery with an X-Buttondown-Signature header, which is the only way the receiver can tell a genuine delivery from anybody who guessed the URL. Automations has no Buttondown inbound receiver of its own, so point this at an endpoint you control and have that endpoint start the workflow.
Buttondown: Delete Advertising Unit
buttondown_delete_advertising_unit
PERMANENTLY delete a sponsorship unit and answer 204 with an empty body. Its slots go with it, including any a sponsor has already bought and supplied content for. Check the slots with Buttondown: List Advertising Slots before deleting the unit they belong to.
Buttondown: Delete Attachment
buttondown_delete_attachment
PERMANENTLY delete an attachment and answer 204 with an empty body. Emails referencing it lose the file. Find the dependants first with Buttondown: List Emails filtered by attachments.
Buttondown: Delete Automation
buttondown_delete_automation
PERMANENTLY delete an automation and answer 204 with an empty body. Queued attempts against it go with it, so subscribers partway through a sequence stop receiving the rest. To stop it temporarily and keep the history, set status to inactive with Buttondown: Update Automation instead.
Buttondown: Delete Comment
buttondown_delete_comment
PERMANENTLY delete a comment and answer 204 with an empty body. Replies to it are affected too. For ordinary moderation prefer Buttondown: Update Comment with status spammy, which hides the comment reversibly; delete is for a removal request.
Buttondown: Delete Email
buttondown_delete_email
PERMANENTLY delete an email and answer 204 with an empty body. Deleting a sent issue removes it from the archive and takes its analytics with it; the copies already in inboxes are unaffected, because nothing recalls those. There is no undo.
Buttondown: Delete External Feed
buttondown_delete_external_feed
PERMANENTLY delete an RSS feed and answer 204 with an empty body. The feed stops being polled and its item history goes with it; emails already generated from it survive as ordinary emails. There is no undo.
Buttondown: Delete Form
buttondown_delete_form
PERMANENTLY delete a form and answer 204 with an empty body. Its public URL stops resolving immediately, so anything embedding or linking to it breaks. Subscribers who signed up through it are unaffected. To take a form down reversibly, set status to inactive instead.
Buttondown: Delete Image
buttondown_delete_image
PERMANENTLY delete an image and answer 204 with an empty body. Any email or archive page still pointing at its URL shows a broken image, including issues already delivered, because those load the image from Buttondown when they are opened. Check before deleting.
Buttondown: Delete Import
buttondown_delete_import
PERMANENTLY delete a subscriber import record and answer 204 with an empty body. Deleting the import record removes the provenance of every subscriber it created, so the subscriber_import filter on Buttondown: List Subscribers stops finding them. The subscribers themselves are not deleted.
Buttondown: Delete Newsletter
buttondown_delete_newsletter
PERMANENTLY delete a whole newsletter and answer 204 with an empty body. This is the single most destructive call in the API: the subscribers, the sent archive, the automations and the analytics all go with it, and nothing here restores any of it. Export first with Buttondown: Create Export if there is any doubt at all.
Buttondown: Delete Note
buttondown_delete_note
PERMANENTLY delete a note and answer 204 with an empty body. There is no update endpoint for notes anywhere in this API, so correcting one means deleting it and creating a replacement.
Buttondown: Delete Price
buttondown_delete_price
PERMANENTLY delete a price and answer 204 with an empty body. Note the path parameter is spelled price_id here rather than the id every other resource uses. Deleting a price that subscribers are currently paying on reaches billing, so check with Buttondown: List Subscribers filtered by current_price before removing one.
Buttondown: Delete Segment
buttondown_delete_segment
PERMANENTLY delete a segment and answer 204 with an empty body. No subscriber is affected, because a segment is a definition rather than a list, but anything that referenced it by id stops resolving. There is no undo.
Buttondown: Delete Snippet
buttondown_delete_snippet
PERMANENTLY delete a snippet and answer 204 with an empty body. Emails still referencing it lose that block of content at render time, so check the dependants with Buttondown: List Emails filtered by snippet_id first. There is no undo.
Buttondown: Delete Subscriber
buttondown_delete_subscriber
PERMANENTLY delete a subscriber and answer 204 with an empty body. This is not an unsubscribe: it removes the record and its history, and nothing here restores it. To stop mailing somebody while keeping the audit trail, use Buttondown: Update Subscriber and set type to unsubscribed. Deleting is the right call for a data-removal request and the wrong call for everything else.
Buttondown: Delete Survey
buttondown_delete_survey
PERMANENTLY delete a survey and answer 204 with an empty body. Its responses go with it, so export them first with Buttondown: Create Export if they matter. To stop collecting without losing anything, set status to inactive instead.
Buttondown: Delete Tag
buttondown_delete_tag
PERMANENTLY delete a tag and answer 204 with an empty body. The tag disappears from every subscriber carrying it, which silently widens the audience of any email or segment whose filters referenced it. Check what depends on a tag before deleting it.
Buttondown: Delete User
buttondown_delete_user
Remove a team member and answer 204 with an empty body. This is how access is revoked, because there is no revoke or suspend field on a user. Their access ends immediately and re-adding them means a fresh invitation they have to accept.
Buttondown: Delete Webhook
buttondown_delete_webhook
PERMANENTLY delete a webhook and answer 204 with an empty body. Deliveries stop immediately and the attempt history goes with it. To stop deliveries reversibly, set status to disabled with Buttondown: Update Webhook.
Buttondown: Invoke Automation
buttondown_invoke_automation
RUNS THE AUTOMATION FOR REAL. Fires an automation manually instead of waiting for its trigger, which means every action it holds executes: if one of them is send_email, real subscribers receive real mail, and nothing here recalls it. Read the automation with Buttondown: Get Automation and check its actions and filters before wiring this into a workflow. Bind an idempotency key to whatever authorised the run.
Buttondown: Poll External Feed
buttondown_poll_external_feed
Poll a feed immediately instead of waiting for its cadence. CAN SEND REAL EMAIL: on a feed whose behaviour is emails, any newly discovered item becomes a sent issue as a direct result of this call, and nothing recalls it. On a draft feed it is safe and just fills the review queue. Check the behaviour with Buttondown: Get External Feed before calling this on a schedule.
Buttondown: Publish Email
buttondown_publish_email
SENDS REAL EMAIL TO REAL SUBSCRIBERS. Publishes a draft to its audience. There is no recall, no undo and no partial send: once Buttondown accepts this, the issue is delivered to everyone the filters match. Every optional field here is a last-moment override applied as part of publishing, so leaving them blank publishes exactly what is stored. Bind an idempotency key to whatever approved the send, because a retried workflow would otherwise mail the whole list twice. Test against a newsletter with Buttondown's test_mode on before wiring this into anything automatic.
Buttondown: Send Email Draft
buttondown_send_email_draft
SENDS REAL EMAIL. Delivers a draft to a named set of people for review. Subscribers takes subscriber ids; recipients takes raw email addresses, which is how you send a proof to an editor who is not on the list. It is not a preview: the recipients receive an actual message. Keep the list short and bind an idempotency key so a retried approval step does not mail the reviewers twice. For a preview with nothing sent, use Buttondown: Get Email Render.
Buttondown: Send Email To Subscriber
buttondown_send_email_to_subscriber
SENDS REAL EMAIL. Delivers an existing email to one subscriber immediately. There is no recall and no undo: once Buttondown accepts the request the message is on its way to a real inbox. Use it for a one-off resend or to give a single reader a back issue. Set an idempotency key bound to whatever triggered the send, because a retried workflow would otherwise mail the same person twice.
Buttondown: Send Subscriber Magic Link
buttondown_send_subscriber_magic_link
SENDS REAL EMAIL. Mails the subscriber a magic link into their own subscriber portal, where they can change their address, manage tags and see their subscription. Use it to answer a support request without handling anybody's credentials. It cannot be recalled, so bind an idempotency key to the request that prompted it.
Buttondown: Send Subscriber Reminder
buttondown_send_subscriber_reminder
SENDS REAL EMAIL. Re-sends the double opt-in confirmation reminder to a subscriber who signed up but never confirmed. Useful as a scheduled sweep over unactivated subscribers, but mail somebody twice and it reads as spam, so bind an idempotency key and keep a record of who has already been reminded.
Buttondown: Skip Subscriber Automation Attempt
buttondown_update_subscriber_automation_attempt
Cancel a queued automation attempt for one subscriber before it runs. Buttondown accepts exactly one value here, 'skipped', so this endpoint does one thing despite looking like a general update, and the node is named for what it does. Use it to pull somebody out of a welcome sequence without disabling the sequence for everyone.
Buttondown: Start Import
buttondown_update_import
STARTS AN IMPORT RUNNING. This looks like an ordinary update and is not: setting status to in_progress is what makes Buttondown execute a validated import, adding every row in the uploaded file to the list. It is why this node is named for the thing it does. There is no cancel and no rollback once it begins, so read the import with Buttondown: Get Import first and confirm the column mapping in its metadata. The other two fields, label and metadata, are safe edits.
Buttondown: Test Webhook
buttondown_test_webhook
Send a test delivery to a webhook's URL and answer 204. It sends no email and changes nothing in Buttondown, but it does make a real POST to a real endpoint, so the receiver sees a genuine-looking payload and should be able to tell it is a test. Use it after creating or repointing a webhook, then read Buttondown: List Webhook Attempts to see what happened.
Buttondown: Update Advertising Slot
buttondown_update_advertising_slot
Moderate or edit one sponsorship slot. The status field here is a VERB rather than a state: Buttondown accepts approve, reject, hold_accept and hold_decline, and each moves the slot through the sponsorship workflow. Approving a slot puts the sponsor's copy into the issue that runs on its date, so it reaches subscribers through the ordinary sending path. The remaining fields correct the ad copy or the sponsor's contact details.
Buttondown: Update Advertising Unit
buttondown_update_advertising_unit
Update a sponsorship unit. UNLIKE EVERY OTHER UPDATE IN THIS CONNECTOR, THIS ONE IS NOT A SAFE PARTIAL EDIT: Buttondown REQUIRES the dates array on this endpoint, and dates is the unit's complete list of slot dates. Sending a shorter list than the unit currently has removes the slots that are missing from it, including sold ones. Read the unit with Buttondown: List Advertising Units first and send back every date you intend to keep.
Buttondown: Update Automation
buttondown_update_automation
Update an automation. The most common use is the smallest one: set status to inactive to pause a sequence without deleting it, and back to active to resume. Passing actions REPLACES the whole list, so read the automation first if you mean to add a step rather than rewrite the sequence.
Buttondown: Update Comment
buttondown_update_comment
Moderate a comment. Status is the only field Buttondown accepts here, so this node approves or rejects and nothing else: 'active' publishes the comment, 'spammy' marks it as spam. Both are reversible, which is why an automated moderation pass is safer here than a delete.
Buttondown: Update Email
buttondown_update_email
Update an email. CAN SEND REAL EMAIL: moving status from draft to about_to_send publishes the issue to its whole audience, which is why this node is flagged destructive even though most edits are harmless. Everything else is a partial update, so a node that only fills in subject changes only the subject. Editing an already-sent email changes the archive copy, not the copies already delivered.
Buttondown: Update External Feed
buttondown_update_external_feed
Update an RSS feed. Changing behaviour from draft to emails is the consequential edit here: it turns a review queue into an automatic sender, and the next poll acts on it. Changing status is the reversible way to pause a feed while a blog is being migrated.
Buttondown: Update Form
buttondown_update_form
Update a hosted form. Setting status to inactive closes it to submissions without deleting it or its history, which is the right move at the end of a campaign. Changing the slug changes the public URL and breaks every existing link to the form.
Buttondown: Update Image
buttondown_update_image
Update an image's metadata. Metadata is the only field Buttondown accepts here, so this node annotates an image rather than replacing it: use it to record where an asset came from, which campaign it belongs to, or its licence.
Buttondown: Update Newsletter
buttondown_update_newsletter
Update a newsletter's settings, including the custom bodies and subjects of its lifecycle emails: the double opt-in confirmation, the post-confirmation welcome, the paid upgrade confirmation and the churn notice. Two things to know before editing lifecycle copy. The confirmation email MUST still contain {{ confirmation_url }} as an HTML link or double opt-in silently breaks. And changing username changes the public archive URL, which breaks every existing link to it.
Buttondown: Update Segment
buttondown_update_segment
Update a segment's name, description or filter rules. Changing the filters changes the audience of every future email that uses this segment, which is the point and also the risk: widen a segment by mistake and the next issue goes to more people than anybody intended.
Buttondown: Update Snippet
buttondown_update_snippet
Update a snippet. Editing the content changes what every email referencing it renders, which is exactly why snippets exist. Changing the IDENTIFIER is the dangerous edit: every email written against the old {{ snippets.<identifier> }} stops resolving. Check the dependants first with Buttondown: List Emails filtered by snippet_id.
Buttondown: Update Subscriber
buttondown_update_subscriber
Update a subscriber. This is a PATCH and there is no PUT anywhere in this API, so fields left blank are left alone rather than cleared. Setting type to unsubscribed is how a workflow unsubscribes somebody; setting it to blocked is how it blocks them. Passing tags REPLACES the whole tag list rather than adding to it, so read the subscriber first if you mean to append.
Buttondown: Update Survey
buttondown_update_survey
Update a survey. Setting status to inactive closes it to new responses without deleting the ones already collected, which is the usual reason to call this. Be careful with answers: responses reference an answer by its POSITION in the list, so reordering or removing a choice silently changes what past responses appear to say.
Buttondown: Update Survey Response
buttondown_update_survey_response
Update the free-text part of a survey response. Text is the only field Buttondown accepts here, and it only applies when the survey has freeform responses enabled: the chosen answer itself cannot be changed after the fact.
Buttondown: Update Tag
buttondown_update_tag
Update a tag. A partial update, so blank fields are left alone. Renaming a tag is worth thinking about first: subscribers carry tags by NAME on the create and update nodes, so a workflow that applies the old name after a rename will create a second tag rather than fail.
Buttondown: Update User
buttondown_update_user
Change a team member's permissions. The permissions object is the only field Buttondown accepts here and it is required, so this node does one thing. Send the WHOLE object: any resource key left out defaults to none, so a partial object silently removes access rather than leaving it alone. Read the user first with Buttondown: Get User and edit what comes back.
Buttondown: Update Webhook
buttondown_update_webhook
Update a webhook: repoint it at a new URL, change which events it listens for, disable it while a receiver is being redeployed, or rotate its signing key. THIS IS THE ONE PATCH IN THE API THAT IS NOT A PARTIAL UPDATE. Buttondown reuses the CREATE schema here, so url and event_types are both required on every call and event_types replaces the whole list. Read the webhook first with Buttondown: Get Webhook and send back the values you are not changing.
Using the integration
Nine nodes send real email, and one of them looks like a create
Publishing is not a database write. Nine nodes in this integration put mail in strangers' inboxes with no recall, no undo and no partial send: Buttondown: Publish Email, Buttondown: Create Email, Buttondown: Update Email, Buttondown: Send Email Draft, Buttondown: Send Email To Subscriber, Buttondown: Send Subscriber Magic Link, Buttondown: Send Subscriber Reminder, Buttondown: Invoke Automation and Buttondown: Poll External Feed. Two of those are not obvious from their names. Invoking an automation runs it for real and automation actions include sending email, and polling an RSS feed whose behaviour is set to emails turns every newly discovered item into a sent issue. Buttondown: Create Bulk Action belongs beside them, because one of its 34 types is a mass send and eight more destroy data. Every one is flagged destructive on the canvas and says what it does in its own description. The create node is the one that needs reading twice, because the safe behaviour there is ours rather than Buttondown's: Buttondown's API defaults a newly created email's status to about_to_send, which means the documented behaviour of a bare create is to mail the whole audience. This integration declares status required with a default of draft instead, so clearing the box restores draft rather than falling through to Buttondown's default, and choosing to send is always a deliberate act. The same reasoning shaped Buttondown: Create External Feed, where the behaviour defaults to creating a draft per item rather than emailing each one, and old items are skipped on the first poll so adding a feed does not process a whole back catalogue.
The API is free. Half of what it touches is not
Buttondown's own API page answers whether the API is available on the free plan with yes, on all plans including free, and there is no API add-on to buy. That is true and it is also the start of the most common confusion here, because Buttondown gates paid features at the product level rather than at the endpoint level. Its pricing page lists the add-ons by name, and several of them are entire object families in this integration: tagging and segmentation, comments and surveys, analytics, automations, RSS-to-email support, sponsorships, email attachments, paid subscriptions, teams, and running more than one newsletter. A free key authenticates perfectly, passes Test Connection, and then returns 403 or an empty list against every one of them. The empty list is the nastier of the two, because Buttondown: List Tags answering with nothing on a free newsletter looks exactly like a newsletter with no tags, and every tag picker in the integration then sits empty for a reason that has nothing to do with the connection. Most nodes in the affected families say so in their own descriptions, though the RSS feed, price and user nodes do not yet, so trust the add-on list over the node text there. Buttondown's pricing page is the authority on which tier includes what, and prices move, so read it there rather than here. Check your plan before you design a workflow around one of these families rather than after.
Idempotency keys, and why they are on 27 nodes
Buttondown implements idempotency keys on Stripe's model and documents them as usable on any request: pass the same X-Idempotency-Key twice and the second call replays the first response instead of doing the work again. That is unusual enough among the APIs this platform connects to that the integration wires it into every node where it matters rather than mentioning it and moving on. The field appears on 27 nodes: every create, everything that sends, and Buttondown: API Request. It resolves three ways. Fill it in and it is sent verbatim, which is what you want when the guarantee should be bound to something upstream such as a form submission id or the id of the record that approved a send. Bind it to something stable rather than to a fresh random value per run, because two runs with two random keys are two different requests and the header protects nothing. Leave it blank inside an automation and the runner derives a key from the execution, which is stable across retries of one run and different across separate runs, so a retried automation does not create a second subscriber and tomorrow's scheduled run is not deduplicated against today's. Leave it blank on an ad-hoc single-node run outside an execution and no header is sent, because there is nothing stable to derive from. Buttondown's limit is 200 characters: a derived key is truncated to fit, while a key you supplied that is too long is refused with a named error rather than cut, since two different keys trimmed to the same length would deduplicate two calls that are not duplicates. One useful side effect from Buttondown's own documentation: an API request record retains its response body only when the request carried an idempotency key, so Buttondown: Get API Request can show what a retried call returned on nodes that use one and cannot on nodes that do not.
Rate limits, and the one that changes what you build
Buttondown documents two limits: 600 requests per minute across all API endpoints, and 100 requests per day against the subscriber create endpoint. The first is generous. The second shapes real workflows, and it arrives on day one of a migration looking like a broken connector rather than a design mismatch, which is why Buttondown: Create Subscriber says so on the node. Buttondown's own guidance names performing an import one subscriber at a time as the first cause of hitting it and points at the import path instead, and the limit does not even answer with a 429: Buttondown returns a 400 whose body points you at the imports endpoint as the supported way to add subscribers in bulk. Treat that node as the path for live signups rather than for backfills. For work across subscribers you already have, Buttondown: Create Bulk Action applies tags, adds notes, rewrites metadata or unsubscribes across a filtered set in a single request. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the last as a unix timestamp in seconds, and a 429 carries a retry delay. This integration reads those headers and attaches them as a hint, and it deliberately does not retry or back off, because a retry loop against the subscriber create endpoint burns a daily quota rather than a per-minute one.
Migrating a list in, and the gap you should know about
Creating an import in Buttondown is a multipart file upload, and this integration builds JSON bodies, so it cannot perform that one call. That is a real gap rather than an oversight, and it is worth naming plainly: because the imports endpoint is the path Buttondown itself recommends over the 100-a-day subscriber create, a fully automated list migration is not possible from here today. What works is the split. Upload the file in Buttondown itself, then Buttondown: List Imports and Buttondown: Get Import confirm it validated and show the detected source and the column mapping in its metadata, and Buttondown: Start Import executes it. Read that last node before you run it. It looks like an ordinary status update and it is not: setting an import's status to in_progress is what makes Buttondown add every row in the file to the list, and there is no cancel and no rollback once it begins. It is named for what it does rather than for the method it uses. The same file-upload limitation covers attachments and images, which are uploaded in Buttondown and then read, referenced and deleted from here.
Subscribers, and three behaviours that surprise people
Buttondown: List Subscribers is the richest query surface in this API and every one of its 48 parameters is typed on the node: lifecycle type, tag, email domain, signup source, form, import, referral code, UTM values, Stripe price and coupon, eleven separate date ranges covering creation, churn, bounce, last open, last click, undeliverability, unsubscription and upgrade, and numeric ranges over open rate, click rate and firewall risk score. Three things about the family are worth knowing before you automate it. Subscriber tags are passed by NAME rather than by id on create and update, and a name that does not exist is created, so those fields are deliberately free text: a picker sourced from the tag lister would offer ids, which the endpoint would then create as new tags named after them. The subscriber endpoints accept an email address in place of an id, which no other resource in this API does, so Buttondown: Get Subscriber and Buttondown: Update Subscriber work with an address directly, and a 404 from one of them usually means a mistyped address rather than a missing person. And collision handling on Buttondown: Create Subscriber is a header rather than a body field, with three behaviours: return the existing subscriber untouched, which is the default, replace it, or fail loudly. Pick the one your workflow actually wants rather than inheriting it.
Pagination, filtering, ordering and expansion
Listers are page-number paginated, returning results with a count and next and previous URLs, driven by a page parameter and, where the endpoint supports one, a page_size. This integration does not follow the next URL automatically, because auto-pagination hides the request count from a caller who is being rate limited; increment page in a loop node when you need more. Two exceptions are worth knowing. Buttondown: List Subscribers accepts page and nothing else, with no page_size, unlike almost every other lister here. And Buttondown: List API Requests is cursor-paginated rather than page-numbered, returning a cursor with no count and no next URL, taking a limit rather than a page size, and Buttondown documents no parameter for sending the cursor back, so page two of that log is not reachable from the documented surface. Narrow it with the date filters instead. On filtering, range filters use __start and __end suffixes and are inclusive at both ends, and Buttondown spells negated filters with a leading hyphen, which makes a poor canvas field name, so they appear as exclude_status, exclude_type, exclude_tag and exclude_domain and are renamed on the wire. Ordering takes a field name with a leading hyphen for descending, and newest first is the default on most listers. Expansion is Stripe-style: related objects come back as ids unless you name them in expand, and the supported values differ per endpoint, so each node lists its own.
Why the API version is pinned, and when to move it
Every request this integration makes carries X-API-Version: 2026-04-01, including the connection test. That matters more here than on most APIs because of how Buttondown resolves a version. It uses the request's own header first; failing that, a version pinned on the newsletter; failing that, the latest version. The third step means an unversioned integration silently rides whatever Buttondown shipped most recently, across a changelog with roughly a hundred dated entries. The second step is the one that settles the argument: an unversioned integration's behaviour would also depend on a setting inside your newsletter that we cannot see, so two identical workflows against two accounts could resolve to two different API versions and neither would say so. Pinning removes both. The practical consequence for you is that a field Buttondown's current documentation describes may be absent from a node's output if it arrived after the pinned version, which is a reason to read the node's own field list rather than the vendor's latest reference. Buttondown does not document what an invalid or retired version returns, so a bump here is treated as a scheduled, tested change rather than something to do reactively.
What the integration blanks out of responses
Buttondown's newsletter object carries a live API key as a required field, described by Buttondown as the key used for authenticating API requests. That means every read, create and update of a newsletter returns a working credential in its body, and so does the newsletter picker that the newsletter context field on 116 nodes reads from. This integration blanks it. The scrubbing covers the newsletter api_key, the webhook signing_key, and any authorization value inside the header maps that API request records return, and it is applied to every node's response rather than to a named subset, because the same object is reachable through expansions and through the picker resolution path. You will see those fields present and empty rather than missing. If a workflow genuinely needs a newsletter's own key, read it in Buttondown rather than routing it through an automation log.
On the automation canvas
Buttondown nodes chain with every other node in Mattering. A form submission or a CRM record can run Buttondown: Create Subscriber with its idempotency key bound to the submission id, so a retried run adds one person rather than two. A weekly schedule can gather material from other connectors, write Buttondown: Create Email as a draft, render it with Buttondown: Get Email Render for a reviewer, open a Mattering Productivity task, and run Buttondown: Publish Email only after somebody approves. A daily schedule can pull churn and undeliverable addresses from Buttondown: List Subscribers into a Mattering database, or read the raw delivery stream from Buttondown: List Events, remembering that the events endpoint accepts no date filter at all, so the only incremental strategy there is to page from the newest end and stop at an event you have already seen. This connector has no trigger nodes, so Buttondown workflows are scheduled or driven by another system's trigger. If you want Buttondown to push to you instead, Buttondown: Create Webhook registers a delivery to a URL you control, Buttondown: Test Webhook fires a test payload at it, and Buttondown: List Webhook Attempts shows what was delivered and what failed.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. Buttondown does not publish an MCP server of its own, and it has said so directly: its API page answers the question with a no, on the grounds that it would rather keep refining its OpenAPI specification than maintain a thin wrapper over it, and it suggests pointing an assistant at that specification to build one fitted to your workflow. This integration is that idea built once and shared, against the same specification, with the fields typed, the destructive nodes flagged, the vendor's send-by-default create turned into a draft and the response scrubbing in place. Buttondown also ships a command-line tool, which is the better answer when a script is all you need. Given what these nodes reach, the sensible split is to hand an assistant the 60 read nodes and the draft-writing ones and keep publishing behind a condition or an approval step, and to enforce that with the credential rather than with the prompt by issuing a key that has no sending permission. The advantage of running Buttondown here rather than in a local assistant config is that the same nodes are canvas steps: the workflow an assistant helps you design then runs on a schedule with nobody present, chains with every other connector, and holds the credential once in a shared workspace store rather than on each person's machine.
What is not included, and the catch-all
Eight of Buttondown's 133 operations are not shipped as nodes. Three are multipart file uploads that a JSON runner cannot execute: uploading an attachment, uploading an image, and creating an import. The other five are the Books endpoints, which drive the bookshelf widget on a Buttondown archive page and which nothing upstream produces and nothing downstream consumes. Everything else is here, including families that need a paid plan, because a 403 on a paid feature is a fact about the account rather than a reason to hide a node. For anything not covered, Buttondown: API Request is the advanced escape hatch: it calls any Buttondown API endpoint directly with a method, a path, a query object and a body object, and inherits everything the typed nodes get, which is the Token authorization header, the pinned API version, the newsletter context, the idempotency key and the response scrubbing. Its path is confined to Buttondown's own base URL so it cannot be pointed at another host carrying your key, and it is flagged destructive because the method is yours to choose and it will happily delete a newsletter. It cannot perform the three file uploads, because those are multipart form posts rather than JSON. Prefer a typed node wherever one exists: they carry the validation, the warnings and the sample output this one cannot.
Troubleshooting
Test Connection fails with a 401, or every node returns 401
A node returns 403 while other nodes on the same credential work
A lister returns an empty array with no error at all
Creating subscribers starts failing with a 400 that mentions imports
Updating a webhook is rejected, or it lost the events it was listening for
Updating a team member removed access they used to have
An email went out when the workflow was only supposed to create a draft
A subscriber node returns 404 for someone who definitely exists
A loop over the API request log never gets past the first page
A field the Buttondown documentation describes is missing from a node's output
Related
The Buttondown MCP
What connecting Buttondown unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Buttondown is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.