Menu
Mattering Automations connector

A Buttondown MCP that defaults to draft

126 nodes across subscribers, emails, tags, segments, forms, imports, automations, RSS-to-email feeds, events, analytics, webhooks, surveys, comments, notes, exports, bulk actions and sponsorship inventory. Nine of them put mail in real inboxes and every one of those says so. Buttondown's own API defaults a newly created email to a status that sends it; this connector defaults it to draft, so the safe thing happens unless somebody deliberately asks for the other thing.

126 ready-made nodes One credential to connect Works with Claude, ChatGPT, and Matter

What the Buttondown MCP connector does

The Buttondown connector for Mattering Automations is 126 nodes on Buttondown's v1 API, pinned to API version 2026-04-01. Sixty of them read and sixty six act. Subscribers, emails and the public archive cover the newsletter itself. Tags, segments, forms, imports and referrals cover how people arrive and how they are grouped. Automations, RSS-to-email feeds and snippets cover what goes out without anybody pressing a button. Events, per-email analytics and Buttondown's own API request log cover what happened afterwards. Websites, teams and money are covered too: webhooks, newsletters, users, prices, coupons, surveys, comments, notes, exports, bulk actions, attachments, images and sponsorship inventory. One node is a catch-all that calls any Buttondown endpoint directly, for anything the typed nodes do not reach.

Every capability is a node on the Automations canvas, and every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. So an assistant can read a month of subscriber churn with Buttondown: List Subscribers, draft next week's issue, and stop at a draft while a person decides whether it goes out. The same nodes are also steps in a scheduled workflow, which is the part a local assistant config cannot do.

The most important thing on this page is that publishing is not a database write. Nine nodes put mail in strangers' inboxes and none of them can be recalled: 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. Buttondown: Create Bulk Action belongs beside them, because one of its types is a mass send and another is a mass delete. Every one of the nine is flagged destructive and says what it does in its own description.

Buttondown: Create Email is the one worth reading twice, because the safe behaviour here is ours rather than the vendor's. Buttondown's own API defaults a new email's status to about_to_send, so the documented behaviour of a bare create is to mail the whole list. This connector declares status required with a default of draft instead, which in this runner means clearing the box restores draft rather than falling through to Buttondown's default. Setting it to about_to_send is then 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 back catalogue.

The Buttondown API is free on every plan, including the free one, and Buttondown says so on its own API page. That is not the same as everything the API touches being free, and the difference is the thing most likely to waste an afternoon. Buttondown sells a long list of features as add-ons rather than gating the API, and its pricing page names them: tagging and segmentation, paid subscriptions, comments and surveys, analytics, RSS-to-email support, sponsorships, email attachments, archives on a custom domain, running more than one newsletter, automations, whitelabeling and teams. That covers roughly half the object families this connector reaches, including tags, surveys, comments, analytics, automations, RSS feeds, sponsorship inventory, attachments, prices and team users. A free key authenticates perfectly, passes the connection test, and then returns 403 or an empty list against those. Check your plan against that list before you build a workflow on top of one, because nothing in the response says whether the cause was your key or your plan.

This connector supports idempotency keys, which is rare. Buttondown implements the header on Stripe's model: send the same X-Idempotency-Key twice and the second call replays the first response instead of doing the work again. Twenty seven nodes offer the field, which is every create, everything that sends, and the catch-all. Leave it blank inside an automation and the runner derives a key from the execution, so it is stable across retries of one run and different between separate runs. That is the difference between a retried workflow sending one newsletter and sending two. Fill it in yourself when you want the guarantee bound to something upstream, such as a form submission id, and bind it to something stable rather than to a fresh random value, which protects nothing.

Two rate limits shape what you can build. Buttondown allows 600 requests per minute across the API, which is generous, and 100 requests per day against the subscriber create endpoint, which is not. Buttondown's own guidance names importing one subscriber at a time as the first cause of hitting it and points at the import path instead. That is why Buttondown: Create Subscriber says so on the node: the failure lands on day one of a migration and looks like a broken connector rather than a design mismatch. For work across existing subscribers, Buttondown: Create Bulk Action is the right answer rather than a loop.

Eight of Buttondown's 133 operations are not here, and it is worth knowing which before you plan a migration. Three are multipart file uploads that a JSON runner cannot execute: uploading an attachment, uploading an image, and creating an import. That last one is the gap that matters, because it is the endpoint Buttondown recommends over the 100-a-day subscriber create, so a fully automated list migration is not possible from here. Upload the file in Buttondown itself and Buttondown: Start Import drives the rest. The other five are the bookshelf endpoints behind the archive page, which nothing upstream produces and nothing downstream consumes. All eight remain reachable through the catch-all if you want them.

One detail that trips people on day one: Buttondown authenticates with the literal word Token in the Authorization header rather than Bearer, and getting it wrong returns a clean 401 that reads exactly like a bad key. The connector writes the prefix itself, so you store the bare key, and it strips a pasted Token or Bearer prefix rather than failing on it. Buttondown keys also carry per-resource permissions across eight areas, each set to write, read or none, and an operation outside them returns 403 rather than 401. Separately, Buttondown's newsletter object contains a live API key as a required field, so the connector blanks that, the webhook signing key and any authorization header on every node's response rather than on a chosen few.

One connection, three surfaces

  • Visual automations. Drag Buttondown nodes onto the canvas and wire them to triggers, conditions, and other apps.
  • AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
  • The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.

Every Buttondown node, ready to drop on the canvas

126 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.

Read and query nodes 60

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

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

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

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

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

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

Get one comment with its text, moderation status, the email it belongs to and when it was posted.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Get one tag with its name, colour, both descriptions, subscriber-editable flag and human-readable secondary id.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Connecting Buttondown takes one credential

Buttondown's own answer to where the key lives is its settings page, under the API section, where keys are managed under Keys. You can create as many keys as you need, and each one carries independent permissions across eight areas of the API: subscribers, emails, sending, newsletter settings, automations, forms, design settings and surveys, each set to write, read or none. One key is special: your account's primary key always has full access, its permissions cannot be changed, and it cannot be deleted, only regenerated. For an automation credential, a purpose-labelled key scoped to what the workflow actually needs is a better idea than the primary one, because it can be revoked on its own. Grant sending access only if you intend to use the nine nodes that send.

1

Sign in to Buttondown and open the API section of your settings, then create a key under Keys. Label it for the workflow it will run, so it can be revoked later without touching anything else.

2

Set that key's permissions deliberately. Read is enough for the 60 query nodes. Sending access is what the nine sending nodes need, and leaving it off is a real safety control rather than an inconvenience. An operation outside a key's permissions returns 403, which is a different finding from a bad key.

3

In Mattering Automations, open Connectors, click Add Connector and choose Buttondown, then click Create new credential and paste the key. Paste the key on its own: if you copy the whole header value out of Buttondown's docs, the connector strips a leading Token or Bearer prefix for you rather than failing on it.

4

Click Test Connection. Mattering calls Buttondown's ping endpoint, which takes no parameters and exists to answer exactly this question. A pass proves the key is valid and the header is right. It does not prove the key has the permissions any particular node needs, and it does not prove your plan includes the features a particular node touches.

5

All 126 Buttondown nodes appear in the canvas palette. Run Buttondown: Ping and then Buttondown: Get Account to confirm which Buttondown account the credential belongs to before anything writes.

6

If your account runs more than one newsletter, set the newsletter context field on the nodes that act inside one. It appears on 116 of the 126 nodes, is sourced from Buttondown: List Newsletters, and stays blank on an ordinary single-newsletter account.

Common uses for the Buttondown MCP

Turn a signup anywhere into a subscriber, exactly once

A form submission, a purchase, a CRM record or a webinar registration can become a Buttondown subscriber without anybody retyping it. Buttondown: Create Subscriber is the node, and the field that makes it trustworthy is the idempotency key: bind it to the submission id and a retried workflow adds one person rather than two. Two behaviours are worth knowing before you wire it. Collision handling is a header rather than a body field, so a repeat address can return the existing subscriber untouched, replace it, or fail loudly, and the default is to leave the existing record alone. And tags are passed by name rather than by id, with any name that does not exist being created, which is powerful and is also how a stray value becomes a permanent tag. The hard ceiling is 100 of these a day, so this node is for live signups rather than backfills.

Draft the issue automatically, publish it only on approval

This is the shape most newsletter automation should take, and the connector is built for it. Buttondown: Create Email writes the issue as a draft, with the body as Markdown or HTML and audience rules in its filters object. Buttondown: Get Email Render returns what it will actually look like, which is the thing a reviewer needs rather than the raw source. A person reads it in a Mattering Productivity task, and only on approval does Buttondown: Publish Email run, with its idempotency key bound to whatever recorded the approval so an accidental re-run does not mail everybody twice. Keeping the draft and the publish as separate steps is the whole point: nothing between them can send by accident.

Watch churn and engagement without a reporting product

Buttondown: List Subscribers is the richest query surface in the API and this node types all 48 of its parameters, including eleven separate date ranges covering creation, churn, bounce, last open, last click, undeliverability, unsubscription and upgrade, plus numeric ranges over open rate, click rate and firewall risk score. Range filters use the __start and __end suffixes and are inclusive at both ends. A weekly scheduled workflow can pull the people who churned in the last seven days, the people whose open rate fell below a threshold, and the addresses that went undeliverable, and write all three into a Mattering database or a Productivity task. Buttondown: List Events reads the raw delivery, open, click, bounce and unsubscribe stream behind those numbers, with one caveat worth designing around: that endpoint accepts no date filter at all, so page from the newest end and stop at an event you have already seen.

Run a comment and survey response queue that a human still owns

Buttondown: List Comments pulls comments by email, by subscriber, by parent or by moderation status, and filtering by status is what makes a real moderation queue possible: pull the pending ones, let an assistant summarise or triage them, and act with Buttondown: Update Comment. Buttondown: List Survey Responses does the same job for structured reader feedback, and it is genuinely useful input for an AI step because the freeform box is usually where the real answers are. One trap to know before you automate against surveys: a response references its answer by 1-based position rather than by text, so reordering a survey's answers re-points every response already recorded against it. Comments and surveys are both paid Buttondown features, so a free newsletter gets an empty list rather than an error.

Keep a sponsorship pipeline out of a spreadsheet

Buttondown: List Advertising Units reads sponsorship inventory with each unit's price, accepted format, character limit, submission deadline and dated slots, and Buttondown: List Advertising Slots reads the slots themselves. Buttondown: Update Advertising Slot is how a sponsor's supplied copy gets attached to a date once it has been approved, which is exactly the step that otherwise lives in someone's inbox. Read the warning on Buttondown: Update Advertising Unit before automating that one: Buttondown requires the complete list of slot dates on every update, so a shorter list removes the missing slots, including ones already sold. Sponsorships are a paid Buttondown feature.

Migrate a list, and export before anything destructive

Buttondown: Create Export starts a background export of subscribers, emails, events, referrals, surveys, comments and more, and Buttondown: Get Export polls it until it is ready. It changes nothing, which makes it the right thing to run before a bulk operation rather than after one. On the way in, upload the file in Buttondown itself, then Buttondown: List Imports and Buttondown: Get Import confirm it validated and Buttondown: Start Import executes it. Read that last one carefully: it looks like an ordinary status update and it is the thing that adds every row in the file to the list, with no cancel and no rollback. For operations across subscribers you already have, Buttondown: Create Bulk Action applies tags, adds notes or rewrites metadata across a filtered set in one call, and several of its 34 types are irreversible, so the type field is the whole decision.

Example: A weekly issue that nobody receives until a person says so

Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.

1

Trigger: a weekly schedule fires. This connector has no trigger nodes, so Buttondown workflows run on a schedule and read rather than listening for a push. If you want Buttondown to push events into Mattering, Buttondown: Create Webhook registers a delivery to a URL you control.

2

Other connectors gather the week's material, and an AI step drafts the issue from it.

3

Buttondown: Create Email writes the draft. The status field is already draft, so nothing has been sent, and the filters object decides which subscribers would receive it when it eventually goes.

4

Buttondown: Get Email Render returns the rendered issue, which is what a reviewer should actually read rather than the raw Markdown.

5

A task is created in Mattering Productivity with the render attached, and the workflow stops there. Everything up to this point is reversible: the draft can be edited or deleted with no consequence to anybody on the list.

6

On approval, Buttondown: Publish Email sends it, with its idempotency key bound to the id of the approval record so that a retried run mails the list once rather than twice.

7

A day later, Buttondown: Get Email Analytics reads deliveries, opens, clicks, failures with per-reason breakdowns, unsubscriptions and replies for that issue, and writes them back onto the task. Those are lifetime-to-date counters for one email rather than a time series, so compare snapshots rather than adding them up. Analytics are a paid Buttondown feature.

Buttondown MCP questions, answered

What can this connector actually do in Buttondown?

126 nodes: 60 read and 66 act. Reads cover subscribers and their referrals, automations and Stripe subscriptions, emails and email history and renders, the public archive, events, per-email and per-automation and per-tag analytics, tags, segments, forms, snippets, imports, exports, webhooks and their delivery attempts, automations, RSS feeds and their items, surveys and responses, comments, notes, attachments, images, prices, coupons, users, newsletters and their sending and hosting domains, the account, Buttondown's own API request log, and a ping. Writes cover creating and updating subscribers, emails, tags, segments, snippets, forms, surveys and responses, comments, notes, automations, RSS feeds, webhooks, users, prices, newsletters and sponsorship units, updating a sponsorship slot or an image, starting exports, imports and bulk actions, plus nineteen deletes and the nine nodes that send mail. Not included: three multipart file uploads that a JSON runner cannot execute, which are uploading an attachment, uploading an image and creating an import, and the five bookshelf endpoints behind the archive page. There are also no trigger nodes, so workflows run on a schedule. Everything cut is still reachable through Buttondown: API Request, the advanced node that calls any Buttondown API endpoint directly.

Does this work with Claude, ChatGPT, or other AI assistants?

Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and work with Buttondown through them. Matter, the assistant built into the platform, uses the same nodes natively. The same nodes are also steps on the automation canvas, so a workflow an assistant helps you design can then run on a schedule with nobody present. Given that nine of these nodes mail real people, 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. A key without sending permission enforces that at Buttondown's end rather than relying on the assistant's judgement.

Does Buttondown publish its own MCP server?

No, and Buttondown has answered the question directly. Its own API page asks whether it has an MCP server and answers no, for the same reason it ships no official SDKs: it would rather keep refining the OpenAPI specification underneath so every caller benefits than maintain a thin wrapper. It suggests pointing an assistant at that specification and having it build a server fitted to your workflow. That is a fair position and this connector is the industrial version of the same idea, built once against the spec rather than per person: 126 nodes with the fields typed, the destructive ones flagged, the vendor's send-by-default create turned into a draft, the response scrubbing that keeps a newsletter's own API key out of your logs, and idempotency keys wired in. What a locally generated server cannot do is the rest of it. These same nodes are steps on an automation canvas, so they run on a schedule with nobody present, chain with every other connector in one workflow, and hold the credential once in a shared workspace store rather than on each person's machine. Buttondown also ships a command-line tool for programmatic use, which is worth knowing if a script is all you need.

Could this send email to my subscribers by accident?

It is the risk worth taking seriously, and the connector is shaped around it. Nine nodes send, each is flagged destructive, and each says so in its own description. The sharpest edge is one the vendor built rather than us: Buttondown's API defaults a newly created email's status to about_to_send, so a bare create against the raw API mails the whole list. Buttondown: Create Email declares status required with a default of draft instead, and clearing the box restores draft rather than falling through, so publishing is always something somebody chose. Three further controls are worth using. Issue the connector a key without sending permission if a workflow has no business sending, and Buttondown refuses at its end with a 403. Bind an idempotency key on any node that sends, so a retried run does not mail the list twice. And test against a newsletter with Buttondown's own test_mode setting turned on, which is the closest thing to a sandbox here: with it on, Buttondown redirects every email to the newsletter's own primary address with a TEST MODE prefix on the subject instead of delivering it to subscribers. Read its limits before relying on it. It applies to the whole newsletter including automations rather than to one email, and Buttondown says test sends still count toward your monthly email allowance.

Is the Buttondown API free, and does everything work on a free plan?

Two different questions with two different answers, and conflating them is the most common way to waste an hour here. The API itself is free: 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. But Buttondown sells a lot of the product as add-ons, and its pricing page lists them by name: tagging and segmentation, paid subscriptions, comments and surveys, analytics, RSS-to-email support, sponsorships, email attachments, archives on a custom domain, running more than one newsletter, automations, whitelabeling and teams. Match that list against what you were planning to automate, because it gates roughly half the object families here, including tags, surveys, comments, analytics, automations, RSS feeds, sponsorship inventory, attachments, prices and team users. A free key authenticates perfectly and passes the connection test in every one of those cases, which is exactly why the failure is confusing: nothing in the response distinguishes a plan gate from a permission gate. Buttondown's pricing page is the authority on what your tier includes, and prices change, so read it there rather than here.

What are Buttondown's rate limits, and can I migrate a list in?

Buttondown documents 600 requests per minute across all API endpoints, and a separate limit of 100 requests per day against the subscriber create endpoint. Every response carries the limit, the remaining count and a reset timestamp as unix seconds, a 429 carries a retry delay, and this connector does not retry or back off, so the workflow decides. The daily subscriber limit is the one that changes what you build: Buttondown's own guidance names importing one subscriber at a time as the first cause of hitting it and points at the import path instead, and Buttondown answers that limit with a 400 pointing at imports rather than with a 429. On migration specifically, be aware of a real gap. Creating an import is a file upload, which this connector cannot perform, so a fully automated migration is not possible from here. Upload the file in Buttondown itself and then Buttondown: Get Import and Buttondown: Start Import drive the rest from a workflow. For operations across subscribers you already have, Buttondown: Create Bulk Action is the right tool rather than a loop.

What stops a retried workflow from doing the same thing twice?

Buttondown supports idempotency keys, implemented on Stripe's model, and this connector wires them in rather than noting them and moving on. Send the same X-Idempotency-Key twice and Buttondown replays the first response instead of doing the work again. The field is offered on 27 nodes, which is every create, every node that sends, and the catch-all. Left blank inside an automation, the runner derives a key from the execution, so it is stable across retries of one run and different across separate runs. That is the correct default in both directions: a retried automation does not create a second subscriber, and tomorrow's scheduled run is not deduplicated against today's. Fill it in yourself when you want the guarantee tied to something upstream, such as a form submission id or an approval record id, and bind it to something stable, because a fresh random value per run protects nothing. Buttondown's limit is 200 characters; a key you supply that is longer is refused with a clear error rather than truncated, since two different keys cut to the same length would deduplicate two calls that are not duplicates. One useful side effect: Buttondown retains a request's response body on its API request log 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.

A node returns 403 but the connection test passes. What is wrong?

Nothing about the credential, which is why the test passed. Buttondown answers 403 for two unrelated reasons and the response body does not say which. The first is key permissions: Buttondown keys carry independent settings across eight areas of the API, each write, read or none, so a key without sending access authenticates perfectly and refuses every node that mails. Check the key under the API section of your Buttondown settings. The second is your plan, because tagging, comments and surveys, analytics, automations, RSS-to-email, sponsorships, attachments, paid subscriptions, teams and running more than one newsletter are all add-ons on Buttondown's pricing page, and on those a free account often gets an empty list rather than an error, which is worse. Two quick tests separate them. Run Buttondown: Ping, which proves the key is valid and nothing more, then run a read node in the same family: if the read works and the write does not, it is permissions, and if neither works, check the plan first.

126 nodes waiting on the canvas

Put Buttondown to work inside your workspace

Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.

All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. Buttondown is a product of its respective owner; Mattering is an independent platform.

Start Free Explore our Products