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

idstring

A unique TypeID associated with the object.

creation_datestring

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

announcement_bar_background_colorstring

The background color for the announcement bar on your archive page. Must be a valid hex color code.

announcement_bar_textstring

Text displayed in the announcement bar on your archive page. Useful for promotions, updates, or calls to action.

announcement_bar_visibilitystring · enum

Controls who sees the announcement bar on your archive page.

values
  • disabled

    The announcement bar is hidden for all visitors.

  • everyone

    The announcement bar is visible to all visitors.

  • free_only

    The announcement bar is visible only to free (non-paying) subscribers.

  • logged_out_only

    The announcement bar is visible only to visitors who are not logged in.

  • paid_only

    The announcement bar is visible only to paid subscribers.

api_keystring

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

archive_themestring · enum

The visual theme for your newsletter's archive page. See archive themes for previews.

values
  • classic

    A traditional newsletter layout with emphasis on readability.

  • modern

    The default theme with a clean, contemporary design.

  • arbus

    An Instagram-inspired grid theme with a three-column layout, ideal for image-heavy newsletters.

  • lovelace

    A minimal, brutalist theme with monospace typography and browser-default styling.

  • myrna

    A theme optimized for long-form reading.

auditing_modestring · enum

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

values
  • disabled

    No IP auditing.

  • enabled

    IP auditing.

  • aggressive

    IP auditing before a subscriber is even created. This mode is admin-only.

cssstring

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

custom_churn_email_bodystring

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

custom_churn_email_subjectstring

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

custom_churn_email_templatestring · enum

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

values
  • classic

    A plaintext template that puts emphasis on your content.

  • custom

    Your own HTML template, wrapped around every email's content.

  • modern

    The default email template.

  • plaintext

    A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.

  • naked

    The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

custom_email_templatestring

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

custom_expired_trial_notification_bodystring

Custom body content for the email sent when a subscriber's free trial expires. Supports template tags.

custom_expired_trial_notification_subjectstring

Custom subject line for the email sent when a subscriber's free trial expires. Supports template tags.

custom_gift_subscription_email_bodystring

Custom body content for the email sent when someone receives a gift subscription. Supports template tags.

custom_gift_subscription_email_subjectstring

Custom subject line for the email sent when someone receives a gift subscription. Supports template tags.

custom_gift_subscription_email_templatestring · enum

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

values
  • classic

    A plaintext template that puts emphasis on your content.

  • custom

    Your own HTML template, wrapped around every email's content.

  • modern

    The default email template.

  • plaintext

    A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.

  • naked

    The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

custom_gift_unsubscription_email_bodystring

Custom body content for the email sent when a gift subscription ends. Supports template tags.

custom_gift_unsubscription_email_subjectstring

Custom subject line for the email sent when a gift subscription ends. Supports template tags.

custom_gift_unsubscription_email_templatestring · enum

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

values
  • classic

    A plaintext template that puts emphasis on your content.

  • custom

    Your own HTML template, wrapped around every email's content.

  • modern

    The default email template.

  • plaintext

    A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.

  • naked

    The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

custom_premium_confirmation_email_bodystring

Custom body content for the email sent when a subscriber upgrades to a paid plan. Supports template tags.

custom_premium_confirmation_email_subjectstring

Custom subject line for the email sent when a subscriber upgrades to a paid plan. Supports template tags.

custom_premium_confirmation_email_templatestring · enum

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

values
  • classic

    A plaintext template that puts emphasis on your content.

  • custom

    Your own HTML template, wrapped around every email's content.

  • modern

    The default email template.

  • plaintext

    A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.

  • naked

    The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

custom_subscription_confirmation_email_subjectstring

Custom subject line for the double opt-in confirmation email sent to new subscribers. Supports template tags.

custom_subscription_confirmation_email_templatestring · enum

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

values
  • classic

    A plaintext template that puts emphasis on your content.

  • custom

    Your own HTML template, wrapped around every email's content.

  • modern

    The default email template.

  • plaintext

    A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.

  • naked

    The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

custom_subscription_confirmation_email_textstring

Custom body content for the double opt-in confirmation email. Must contain {{ confirmation_url }} as an HTML or Markdown link.

custom_subscription_confirmation_reminder_email_subjectstring

Custom subject line for the reminder email sent to subscribers who haven't confirmed. Supports template tags.

custom_subscription_confirmation_reminder_email_textstring

Custom body content for the reminder email sent to subscribers who haven't confirmed. Supports template tags.

custom_subscription_confirmed_email_subjectstring

Custom subject line for the email sent after a subscriber confirms their subscription. Supports template tags.

custom_subscription_confirmed_email_textstring

Custom body content for the email sent after a subscriber confirms their subscription. Supports template tags.

descriptionstring

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

domainstring

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

email_addressstring

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

email_domainstring

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

enabled_featuresarray

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

footerstring

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

from_namestring

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

headerstring

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

hosting_domain_statusstring · enum

The DNS verification status of your custom hosting domain. Read-only; see /newsletters/{id}/hosting-domain for the underlying records.

values
  • none

    No custom hosting domain is configured.

  • invalid

    The required DNS records are missing or misconfigured.

  • valid

    The DNS records are correct and the hosting domain is verified.

iconstring

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

icon_alt_textstring

Alt text for the newsletter icon, used by screen readers and shown when the image cannot load.

imagestring

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

localestring · enum

The language/locale for your newsletter's UI elements (confirmation emails, unsubscribe pages, etc.). See localization for supported locales.

values
  • cs-CZ

    Czech (Czech Republic).

  • nl-NL

    Dutch (Netherlands).

  • en-AU

    English (Australia).

  • en-CA

    English (Canada).

  • en-GB

    English (United Kingdom).

  • en

    English (United States).

  • et

    Estonian.

  • fi-FI

    Finnish (Finland).

  • fr

    French.

  • de

    German.

  • it

    Italian.

  • ja-JP

    Japanese (Japan).

  • ne

    Nepali.

  • nb-NO

    Norwegian.

  • pl-PL

    Polish (Poland).

  • pt-BR

    Portuguese (Brazil).

  • pt-PT

    Portuguese (Portugal).

  • ru

    Russian.

  • es

    Spanish.

  • tr

    Turkish.

  • sv-SE

    Swedish (Sweden).

metadataobject

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

namestring

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

reply_to_addressstring

An alternative email address that receives replies to your newsletter emails, instead of the sending address.

sending_domain_statusstring · enum

The DNS verification status of your custom sending domain. Read-only; see /newsletters/{id}/sending-domain for the underlying records.

values
  • none

    No custom sending domain is configured.

  • invalid

    The required DNS records are missing or point somewhere incorrect.

  • awaiting_ssl

    The DNS records are correct and a TLS certificate is still being issued for the tracking host. This is transient and usually resolves within a few minutes.

  • failing

    The DNS records are correct but the tracking host is not yet serving traffic over HTTPS.

  • deliberately_cold

    The DNS records are correct, but the tracking host has been temporarily unregistered because the newsletter has not sent recently. Sending again automatically re-verifies it.

  • valid

    The DNS records are correct and the sending domain is fully verified.

sharing_networksarray

A list of social networks to show share buttons for on your archive pages.

socialsarray

A list of social media accounts linked to your newsletter, displayed on your archive page. Each entry has a type, url, and optional label.

sortstring

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

subscription_confirmation_redirect_urlstring

A URL to redirect subscribers to after they confirm their subscription via double opt-in.

subscription_redirect_urlstring

A URL to redirect subscribers to immediately after they submit the subscription form (before confirmation).

templatestring · enum

The default email template for your newsletter. See email templates for available options.

values
  • classic

    A plaintext template that puts emphasis on your content.

  • custom

    Your own HTML template, wrapped around every email's content.

  • modern

    The default email template.

  • plaintext

    A plaintext (like, literally plaintext, no HTML at all) template for the truly minimalist.

  • naked

    The email body itself is used as the template, with no outside scaffolding provided by Buttondown.

test_modeboolean

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

theme_configurationobject

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

timezonestring

The timezone used for scheduling and displaying dates in your newsletter (e.g., 'America/New_York', 'Europe/London').

tint_colorstring

The accent color for your newsletter's emails, applied to links and buttons. Your archive's accent color is set separately, by its theme. Must be a valid hex color code.

usernamestring

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

web_cssstring

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