{"openapi":"3.1.0","info":{"title":"Buttondown (BYOK) API","version":"0.1.0","description":"Buttondown (BYOK) lets an AI assistant read your own Buttondown data through the Buttondown API with a key you supply (API key). Read-only: 7 tools (list_subscribers, get_subscriber, list_emails, get_email, get_email_analytics, list_tags, list_surveys). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-buttondown.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-buttondown/docs"},"termsOfService":"https://connectorbay.com/byok-buttondown/terms"},"servers":[{"url":"https://byok-buttondown.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-buttondown/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_subscribers":{"post":{"operationId":"list_subscribers","summary":"List subscribers with email, type (regular, premium, unsubscribed ...), source, signup date, country, tags and open and ","description":"List subscribers with email, type (regular, premium, unsubscribed ...), source, signup date, country, tags and open and click statistics. Filter by email text, type, source, tag or signup dates. Use for \"Show my newest Buttondown subscribers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email_address":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers whose email address contains this text.","title":"Email Address"},"type":{"anyOf":[{"enum":["blocked","complained","churning","churned","gifted","unactivated","unpaid","undeliverable","premium","past_due","paused","regular","removed","trialed","unsubscribed","upcoming"],"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers of this type.","title":"Type"},"source":{"anyOf":[{"enum":["admin","api","carrd","comment","embedded_form","form","import","memberful","netlify","organic","patreon","shopify","stripe","user","zapier"],"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers who came from this source.","title":"Source"},"tag":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers carrying this tag.","title":"Tag"},"date_start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers created on or after this day, yyyy-mm-dd.","title":"Date Start"},"date_end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers created on or before this day, yyyy-mm-dd.","title":"Date End"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Buttondown does not document the page size).","title":"Page"}},"title":"list_subscribersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_subscriber":{"post":{"operationId":"get_subscriber","summary":"Get one subscriber by ID or email address, with type, source, dates, country, tags and open and click statistics. Use fo","description":"Get one subscriber by ID or email address, with type, source, dates, country, tags and open and click statistics. Use for \"Look up jane@example.com in Buttondown\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id_or_email":{"description":"The subscriber's ID or email address.","maxLength":200,"title":"Id Or Email","type":"string"}},"required":["id_or_email"],"title":"get_subscriberArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_emails":{"post":{"operationId":"list_emails","summary":"List emails (drafts, scheduled and sent) with subject, status, type, dates and archive URL; bodies are left out. Filter ","description":"List emails (drafts, scheduled and sent) with subject, status, type, dates and archive URL; bodies are left out. Filter by status, subject text or publish dates. Only reads; never sends. Use for \"What were my last sent Buttondown emails\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["draft","managed_by_rss","about_to_send","scheduled","in_flight","paused","deleted","errored","sent","partially_sent","imported","throttled","resending","transactional","suppressed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only emails with this status.","title":"Status"},"subject":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails whose subject contains this text.","title":"Subject"},"publish_date_start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails published on or after this day, yyyy-mm-dd.","title":"Publish Date Start"},"publish_date_end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only emails published on or before this day, yyyy-mm-dd.","title":"Publish Date End"},"ordering":{"anyOf":[{"enum":["creation_date","-creation_date","status","-status","publish_date","-publish_date","subject","-subject","email_type","-email_type","modification_date","-modification_date","clicks","-clicks","opens","-opens","click_rate","-click_rate","open_rate","-open_rate","page_views_lifetime","-page_views_lifetime","unsubscriptions","-unsubscriptions","subscriptions","-subscriptions","paid_subscriptions","-paid_subscriptions","replies","-replies","comments","-comments"],"type":"string"},{"type":"null"}],"default":"-publish_date","description":"Sort field; prefix with - for descending, for example -publish_date.","title":"Ordering"},"excluded_fields":{"anyOf":[{"const":"body","type":"string"},{"type":"null"}],"default":"body","description":"Fields to leave out of each email; body is the only allowed value and keeps answers small.","title":"Excluded Fields"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Buttondown does not document the page size).","title":"Page"}},"title":"list_emailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_email":{"post":{"operationId":"get_email","summary":"Get one email by ID with subject, status, type, dates, archive URL and description. Use for \"Show Buttondown email em_1\"","description":"Get one email by ID with subject, status, type, dates, archive URL and description. Use for \"Show Buttondown email em_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email_id":{"description":"The email's ID, for example 'em_...' (from list_emails).","maxLength":200,"title":"Email Id","type":"string"}},"required":["email_id"],"title":"get_emailArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_email_analytics":{"post":{"operationId":"get_email_analytics","summary":"Get one email's delivery analytics: recipients, deliveries, opens, clicks, failures, unsubscriptions, complaints, page v","description":"Get one email's delivery analytics: recipients, deliveries, opens, clicks, failures, unsubscriptions, complaints, page views and new subscriptions. Use for \"How did Buttondown email em_1 perform\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email_id":{"description":"The email's ID, for example 'em_...' (from list_emails).","maxLength":200,"title":"Email Id","type":"string"}},"required":["email_id"],"title":"get_email_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List the tags used to group subscribers with ID, name, color, description and creation date. Use for \"What tags do I use","description":"List the tags used to group subscribers with ID, name, color, description and creation date. Use for \"What tags do I use in Buttondown\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many tags per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Buttondown does not document the page size).","title":"Page"}},"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_surveys":{"post":{"operationId":"list_surveys","summary":"List surveys with identifier, question, status, answers and response count. Use for \"Which surveys do I have in Buttondo","description":"List surveys with identifier, question, status, answers and response count. Use for \"Which surveys do I have in Buttondown and how many responses\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"Only surveys with this status.","title":"Status"},"ordering":{"anyOf":[{"enum":["creation_date","-creation_date","question","-question","identifier","-identifier","status","-status","response_count","-response_count"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field; prefix with - for descending.","title":"Ordering"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Buttondown does not document the page size).","title":"Page"}},"title":"list_surveysArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}