Buttondown MCP by usefulapi

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

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

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.

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

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

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

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.

{
  "type": "object",
  "properties": {
    "email_address": {
      "description": "Only subscribers whose e-mail address contains this text.",
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "type": {
      "description": "Only subscribers of these types (e.g. regular, unactivated, unsubscribed).",
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "blocked",
          "complained",
          "churning",
          "churned",
          "gifted",
          "unactivated",
          "unpaid",
          "undeliverable",
          "premium",
          "past_due",
          "paused",
          "regular",
          "removed",
          "trialed",
          "unsubscribed",
          "upcoming"
        ]
      }
    },
    "not_type": {
      "description": "Exclude subscribers of these types.",
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "blocked",
          "complained",
          "churning",
          "churned",
          "gifted",
          "unactivated",
          "unpaid",
          "undeliverable",
          "premium",
          "past_due",
          "paused",
          "regular",
          "removed",
          "trialed",
          "unsubscribed",
          "upcoming"
        ]
      }
    },
    "tag": {
      "description": "Only subscribers with these tag names.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    },
    "domain": {
      "description": "Only subscribers whose e-mail domain is one of these.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 253
      }
    },
    "created_after": {
      "description": "Only subscribers created on or after this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "created_before": {
      "description": "Only subscribers created before this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "ordering": {
      "description": "Sort field, - for descending (default -creation_date).",
      "type": "string",
      "pattern": "^-?[a-z_]{1,40}$"
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

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

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.

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

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}.

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

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.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Only emails with these statuses (draft, scheduled, sent, ...).",
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "draft",
          "managed_by_rss",
          "about_to_send",
          "scheduled",
          "in_flight",
          "paused",
          "deleted",
          "errored",
          "sent",
          "partially_sent",
          "imported",
          "throttled",
          "resending",
          "transactional",
          "suppressed"
        ]
      }
    },
    "subject": {
      "description": "Only emails whose subject contains this text.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "created_after": {
      "description": "Only emails created on or after this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "created_before": {
      "description": "Only emails created before this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "published_after": {
      "description": "Only emails published on or after this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "published_before": {
      "description": "Only emails published before this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "ordering": {
      "description": "Sort order (default -creation_date).",
      "type": "string",
      "enum": [
        "creation_date",
        "-creation_date",
        "publish_date",
        "-publish_date",
        "modification_date",
        "-modification_date",
        "subject",
        "-subject",
        "status",
        "-status"
      ]
    },
    "include_body": {
      "description": "Include each email's full body (large). Default false.",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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

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

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

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

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.

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

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}.

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

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

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

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

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

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.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "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": {
      "description": "Internal description (only you see it).",
      "type": "string",
      "maxLength": 1000
    },
    "public_description": {
      "description": "Public description shown in the subscriber portal.",
      "type": "string",
      "maxLength": 1000
    },
    "subscriber_editable": {
      "description": "Let subscribers add/remove this tag themselves. Default false.",
      "type": "boolean"
    }
  },
  "required": [
    "name",
    "color"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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