buttondown_add_subscriber

WRITE: add ONE subscriber by e-mail address. No subscriber type is set, so Buttondown applies the newsletter's normal sign-up rules (double opt-in: the subscriber is typically created as unactivated and Buttondown e-mails THAT ONE address a confirmation message; opt-in is never bypassed, nor is the firewall). Only add people who asked to subscribe. Creating a subscriber (and its tags) can also start the newsletter's own automations, which may e-mail that one subscriber. An existing e-mail is left untouched (error, no overwrite). Optional tags (a tag that does not exist is created, which needs a plan with tags), a private note and metadata. Buttondown limits creation to 100 subscribers per day. POST /subscribers.

Argument	Type	Description
tags	array	Tag names to apply.
notes	string	Private note (never shown to the subscriber).
metadata	object	Free-form key-value data stored on the subscriber.
utm_medium	string
utm_source	string
referrer_url	string	Where the subscriber came from.
utm_campaign	string
email_address*	string	The new subscriber's e-mail address. They receive the confirmation e-mail.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "email_address"
  ],
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 20,
      "description": "Tag names to apply."
    },
    "notes": {
      "type": "string",
      "maxLength": 5000,
      "description": "Private note (never shown to the subscriber)."
    },
    "metadata": {
      "type": "object",
      "description": "Free-form key-value data stored on the subscriber.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "utm_medium": {
      "type": "string",
      "maxLength": 300
    },
    "utm_source": {
      "type": "string",
      "maxLength": 300
    },
    "referrer_url": {
      "type": "string",
      "maxLength": 2000,
      "description": "Where the subscriber came from."
    },
    "utm_campaign": {
      "type": "string",
      "maxLength": 300
    },
    "email_address": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$",
      "maxLength": 254,
      "description": "The new subscriber's e-mail address. They receive the confirmation e-mail."
    }
  }
}

buttondown_create_email_draft

WRITE: create a DRAFT email (status always "draft"). Nothing is sent or scheduled and no subscriber is e-mailed; to send it, the user must open the draft in Buttondown and send it there. This server has no tool that sends or schedules email. Body is Markdown or HTML. POST /emails.

Argument	Type	Description
body	string	Email body in Markdown (or HTML).
slug	string	Archive URL slug.
image	string	Preview image URL.
subject*	string	Subject line.
description	string	Short description used for archives and SEO.
canonical_url	string	URL of the original source of the content.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "subject"
  ],
  "properties": {
    "body": {
      "type": "string",
      "maxLength": 500000,
      "description": "Email body in Markdown (or HTML)."
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_-]{1,100}$",
      "description": "Archive URL slug."
    },
    "image": {
      "type": "string",
      "maxLength": 2000,
      "description": "Preview image URL."
    },
    "subject": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "Subject line."
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "Short description used for archives and SEO."
    },
    "canonical_url": {
      "type": "string",
      "maxLength": 2000,
      "description": "URL of the original source of the content."
    }
  }
}

buttondown_create_tag

WRITE: create a subscriber tag (needs a Buttondown plan with tags). An existing tag with the same name is returned as an error and not changed. POST /tags.

Argument	Type	Description
name*	string	Tag name (up to 100 characters).
color*	string	Hex color, e.g. #FFD700.
description	string	Internal description (only you see it).
public_description	string	Public description shown in the subscriber portal.
subscriber_editable	boolean	Let subscribers add/remove this tag themselves. Default false.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name",
    "color"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Tag name (up to 100 characters)."
    },
    "color": {
      "type": "string",
      "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
      "description": "Hex color, e.g. #FFD700."
    },
    "description": {
      "type": "string",
      "maxLength": 1000,
      "description": "Internal description (only you see it)."
    },
    "public_description": {
      "type": "string",
      "maxLength": 1000,
      "description": "Public description shown in the subscriber portal."
    },
    "subscriber_editable": {
      "type": "boolean",
      "description": "Let subscribers add/remove this tag themselves. Default false."
    }
  }
}

buttondown_get_account

The Buttondown account this API key belongs to: username and e-mail address. GET /accounts/me.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

buttondown_get_automation

One automation by id with its trigger, actions and filters. GET /automations/{id}.

read-only

Argument	Type	Description
automation_id*	string	The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "automation_id"
  ],
  "properties": {
    "automation_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...)."
    }
  }
}

buttondown_get_automation_analytics

Performance numbers for one automation. GET /automations/{id}/analytics.

read-only

Argument	Type	Description
automation_id*	string	The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "automation_id"
  ],
  "properties": {
    "automation_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...)."
    }
  }
}

buttondown_get_email

One email by id with its full body, subject, status, publish date, slug, archive settings and analytics summary. GET /emails/{id}.

read-only

Argument	Type	Description
email_id*	string	The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "email_id"
  ],
  "properties": {
    "email_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...)."
    }
  }
}

buttondown_get_email_analytics

Delivery and engagement numbers for one sent email: recipients, deliveries, opens, clicks, failures, unsubscriptions, complaints, replies, page views. GET /emails/{id}/analytics.

read-only

Argument	Type	Description
email_id*	string	The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "email_id"
  ],
  "properties": {
    "email_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...)."
    }
  }
}

buttondown_get_newsletter

One newsletter by id (settings and identity only; no API key, CSS or templates). GET /newsletters/{id}.

read-only

Argument	Type	Description
newsletter_id*	string	The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "newsletter_id"
  ],
  "properties": {
    "newsletter_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...)."
    }
  }
}

buttondown_get_subscriber

One subscriber by id or by e-mail address: type, tags, notes, metadata, source, engagement and lifecycle dates. GET /subscribers/{id_or_email}.

read-only

Argument	Type	Description
id_or_email*	string	The subscriber's id or e-mail address.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id_or_email"
  ],
  "properties": {
    "id_or_email": {
      "type": "string",
      "maxLength": 254,
      "minLength": 1,
      "description": "The subscriber's id or e-mail address."
    }
  }
}

buttondown_get_tag_analytics

Subscribers created, open rate and click rate for one tag. GET /tags/{id}/analytics.

read-only

Argument	Type	Description
tag_id*	string	Tag id (see buttondown_list_tags).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "tag_id"
  ],
  "properties": {
    "tag_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Tag id (see buttondown_list_tags)."
    }
  }
}

buttondown_list_automations

List automations (welcome sequences and other triggered e-mails) with name, status, trigger, actions and filters (webhook URLs in actions are shown by host only). Read-only: automations are not started or changed. GET /automations.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_list_emails

List emails (drafts, scheduled and sent), newest first by default, with subject, status, publish date, slug, archive URL and analytics summary. The body is left out unless include_body is set. Filter by status, subject text or date. GET /emails.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
status	array	Only emails with these statuses (draft, scheduled, sent, ...).
subject	string	Only emails whose subject contains this text.
ordering	string	Sort order (default -creation_date).
include_body	boolean	Include each email's full body (large). Default false.
created_after	string	Only emails created on or after this date (yyyy-mm-dd).
created_before	string	Only emails created before this date (yyyy-mm-dd).
published_after	string	Only emails published on or after this date (yyyy-mm-dd).

buttondown_list_events

List delivery events (delivered, opened, clicked, bounced, unsubscribed, ...), newest first, optionally for one email or subscriber. GET /events.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
email_id	string	Only events for this email.
page_size	integer	Results per page, 1-500 (default 100).
event_type	string	Only events of this type.
subscriber_id	string	Only events for this subscriber (id, not e-mail).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "email_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Only events for this email."
    },
    "page_size": {
      "type": "integer",
      "maximum": 500,
      "minimum": 1,
      "description": "Results per page, 1-500 (default 100)."
    },
    "event_type": {
      "enum": [
        "bounced",
        "clicked",
        "complained",
        "delivered",
        "opened",
        "rejected",
        "replied",
        "unsubscribed"
      ],
      "type": "string",
      "description": "Only events of this type."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Only events for this subscriber (id, not e-mail)."
    }
  }
}

buttondown_list_forms

List sign-up forms with title, slug, status, tags and subscriber counts. GET /forms.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_list_newsletters

List the newsletters on the account with name, username, domains, sender, locale and timezone. The newsletter's API key, custom CSS and e-mail templates are never returned. GET /newsletters.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_list_segments

List saved subscriber segments with name, description and filters. GET /segments.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_list_snippets

List reusable content snippets with identifier, name, mode and how often each is referenced. GET /snippets.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_list_subscribers

List or search subscribers (newest first by default) with e-mail, type (regular, unactivated, unsubscribed, premium, ...), tags, notes, metadata, source, open/click rates and dates. Filter by e-mail text, type, tag, signup date or domain. GET /subscribers.

read-only

Argument	Type	Description
tag	array	Only subscribers with these tag names.
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
type	array	Only subscribers of these types (e.g. regular, unactivated, unsubscribed).
domain	array	Only subscribers whose e-mail domain is one of these.
not_type	array	Exclude subscribers of these types.
ordering	string	Sort field, - for descending (default -creation_date).
created_after	string	Only subscribers created on or after this date (yyyy-mm-dd).
email_address	string	Only subscribers whose e-mail address contains this text.

buttondown_list_survey_responses

List survey responses (who answered what), optionally for one survey, email or subscriber. GET /survey_responses.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
email_id	string	Only responses submitted from this email.
survey_id	string	Only responses to this survey.
created_after	string	A date, yyyy-mm-dd.
subscriber_id	string	Only responses by this subscriber (id, not e-mail).
created_before	string	A date, yyyy-mm-dd.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "email_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Only responses submitted from this email."
    },
    "survey_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Only responses to this survey."
    },
    "created_after": {
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
      "description": "A date, yyyy-mm-dd."
    },
    "subscriber_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Only responses by this subscriber (id, not e-mail)."
    },
    "created_before": {
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
      "description": "A date, yyyy-mm-dd."
    }
  }
}

buttondown_list_surveys

List surveys with question, answers, status and response count. GET /surveys.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.
status	string	Only surveys with this status.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    },
    "status": {
      "enum": [
        "active",
        "inactive"
      ],
      "type": "string",
      "description": "Only surveys with this status."
    }
  }
}

buttondown_list_tags

List subscriber tags with name, color, descriptions and whether subscribers can edit them. GET /tags.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_list_webhooks

List configured webhooks with status and subscribed event types. The signing key is never returned and the URL is shown by host only. GET /webhooks.

read-only

Argument	Type	Description
page	integer	Page number, from 1 (default 1). Pass the previous reply's next_page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 100000,
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "exclusiveMinimum": 0
    }
  }
}

buttondown_update_email_draft

WRITE: edit the subject, body, description, slug or preview image of an email that is still a DRAFT (replaces those fields; the previous text is lost unless Buttondown's email history is used). Refuses any email that is not a draft, and never changes status or publish date, so nothing is sent or scheduled. PATCH /emails/{id}.

destructive

Argument	Type	Description
body	string	New body in Markdown (or HTML); replaces the whole body.
slug	string
image	string
subject	string
email_id*	string	The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...).
description	string
canonical_url	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "email_id"
  ],
  "properties": {
    "body": {
      "type": "string",
      "maxLength": 500000,
      "description": "New body in Markdown (or HTML); replaces the whole body."
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_-]{1,100}$"
    },
    "image": {
      "type": "string",
      "maxLength": 2000
    },
    "subject": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "email_id": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The object's Buttondown id (a UUID or a prefixed id such as em_..., sub_..., tag_...)."
    },
    "description": {
      "type": "string",
      "maxLength": 2000
    },
    "canonical_url": {
      "type": "string",
      "maxLength": 2000
    }
  }
}

buttondown_update_subscriber

WRITE: change ONE subscriber's tags, private note or metadata. Tags are merged (add_tags / remove_tags change only those names; the others stay). A given note or metadata replaces the existing value (destructive for that field). The subscriber's type (unsubscribe, block, ...) and e-mail address cannot be changed here, and this tool sends nothing itself; but a tag, note or metadata change can start the newsletter's own automations (for example a tag-triggered welcome sequence), which may e-mail that one subscriber. PATCH /subscribers/{id_or_email}.

destructive

Argument	Type	Description
notes	string	Replace the private note with this text (empty string clears it).
add_tags	array	Tag names to add.
metadata	object	Replace the subscriber's metadata object with this one.
id_or_email*	string	The subscriber's id or e-mail address.
remove_tags	array	Tag names to remove.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id_or_email"
  ],
  "properties": {
    "notes": {
      "type": "string",
      "maxLength": 5000,
      "description": "Replace the private note with this text (empty string clears it)."
    },
    "add_tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 20,
      "minItems": 1,
      "description": "Tag names to add."
    },
    "metadata": {
      "type": "object",
      "description": "Replace the subscriber's metadata object with this one.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "id_or_email": {
      "type": "string",
      "maxLength": 254,
      "minLength": 1,
      "description": "The subscriber's id or e-mail address."
    },
    "remove_tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "maxItems": 20,
      "minItems": 1,
      "description": "Tag names to remove."
    }
  }
}

Buttondown MCP by usefulapi

Try it

buttondown_add_subscriber

Buttondown MCP by usefulapi

Try it

buttondown_add_subscriber

Tools (25)