Buttondown logo

IntroductionAuditing modes

Routes

Listing newslettersCreating a newsletterUpdating a newsletterDeleting a newsletter

Buttondown logo

Introduction

You will likely not need to interact with your newsletter settings programmatically, but if you do, this is the endpoint for you. You can create, update, and list newsletters via the API; this is ideal for integrating with Buttondown as a headless email or newsletter provider (e.g. for a SaaS product.)

{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}

Fields

id

Type
string
Description

A unique TypeID associated with the object.

creation_date

Type
string
Description

The date and time at which the object was first created.

api_key

Type
string
Description

The API key for this newsletter, used for authenticating API requests.

auditing_mode

Type
NewsletterAuditingMode
Description

The auditing mode for your newsletter, which controls spam and abuse protection. See the Firewall for more information.

css

Type
string
Description

Custom CSS styling applied to your newsletter emails. See CSS customization for more information.

theme_configuration

Type
object
Description

Custom theme configuration (variables) for your newsletter. These can be referenced in your CSS and templates to maintain consistent styling.

email_theme_configuration

Type
object
Description

A dictionary of CSS token overrides for the email theme.

custom_churn_email_body

Type
string
Description

Custom body content for the email sent when a paid subscriber cancels. Supports template tags like {{ subscriber.email }} and {{ newsletter.name }}.

custom_churn_email_subject

Type
string
Description

Custom subject line for the email sent when a paid subscriber cancels. Supports template tags like {{ newsletter.name }}.

custom_churn_email_template

Type
string
Description

The email template to use for churn emails. If not set, uses the newsletter's default template.

custom_email_template

Type
string
Description

The identifier for a custom email template. See email templates for available options.

description

Type
string
Description

A brief description of your newsletter, displayed on your public archive page and used for SEO.

domain

Type
string
Description

The custom domain where your newsletter archives are hosted (e.g., 'newsletter.example.com'). See custom domains for setup instructions.

email_address

Type
string
Description

The 'From' email address used when sending your newsletter. Must be verified before use.

email_domain

Type
string
Description

The custom domain from which your newsletter emails are sent (e.g., 'mail.example.com'). See sending domains for setup instructions.

enabled_features

Type
array
Description

A list of features enabled for your newsletter. Common values include 'archives', 'portal', 'surveys', 'comments', 'paid_subscriptions', 'automations', 'webhooks', 'tracking', and 'referrals'.

Type
string
Description

HTML content displayed at the bottom of your newsletter emails. Supports template tags.

from_name

Type
string
Description

The display name shown in the 'From' field of your emails (e.g., 'Jane from Acme Newsletter').

Type
string
Description

HTML content displayed at the top of your newsletter emails. Supports template tags.

icon

Type
string
Description

URL to your newsletter's icon image, used as a favicon and in various UI contexts.

image

Type
string
Description

URL to your newsletter's header or branding image, displayed on archive pages and in social previews.

metadata

Type
object
Description

A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested — you can store objects and arrays within your metadata. (You can read more about metadata.)

name

Type
string
Description

The display name of your newsletter, shown to subscribers and on your archive page.

sort

Type
string
Description

The default sorting method for listing subscribers or messages. Example values: 'creation_date', '-creation_date', 'email_address'.

test_mode

Type
boolean
Description

Whether test mode is enabled. When enabled, emails are not actually sent to subscribers, useful for testing automations and workflows.

tint_color

Type
string
Description

The accent color for your newsletter, used in emails and on your archive page. Must be a valid hex color code.

username

Type
string
Description

The unique URL-safe identifier for your newsletter, used in your archive URL (e.g., 'buttondown.com/username').

web_css

Type
string
Description

Custom CSS styling applied to your newsletter's web presence (archive pages, subscription forms, etc.).