Buttondown logo

Get started

Routes

IntroductionAnnouncement bar visibilityArchive themesAuditing modesLocales

Routes

Listing newslettersCreating a newsletterUpdating a newsletterDeleting a newsletter

Buttondown logo

Updating a newsletter

Sample requests

These sample requests are autogenerated by the OpenAPI spec. This endpoint requires one or more parameters in the URL: those are offset in curly-braces.

import requests

url = "https://api.buttondown.com/v1/newsletters/{id}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "announcement_bar_background_color": "#FF6600",
  "announcement_bar_text": "Subscribe to get 20% off your first order!",
  "css": ".header { color: #000; }",
  "custom_churn_email_body": "Hi {{ subscriber.email }},\n\nWe're sorry to see you go!",
  "custom_churn_email_subject": "You've canceled your premium subscription to {{ newsletter.name }}",
  "custom_churn_email_template": "modern",
  "custom_email_template": "modern",
  "custom_expired_trial_notification_template": "modern",
  "custom_gift_subscription_email_template": "modern",
  "custom_gift_unsubscription_email_template": "modern",
  "custom_premium_confirmation_email_template": "modern",
  "custom_subscription_confirmation_email_template": "modern",
  "description": "Stay up to date with the latest trends in wigs and hairpieces",
  "domain": "sheinhardt.com",
  "email_address": "newsletter@sheinhardt.com",
  "email_domain": "mail.sheinhardt.com",
  "email_theme_configuration": {
    "primary-color": "#0069FF"
  },
  "enabled_features": [
    "archives",
    "portal",
    "surveys"
  ],
  "footer": "<p>Thanks for reading!</p>",
  "from_name": "Sheinhardt Wig Company",
  "header": "<p>Welcome to our newsletter!</p>",
  "icon": "https://example.com/icon.png",
  "image": "https://example.com/header.jpg",
  "metadata": {
    "source": "my-app",
    "tier": "pro"
  },
  "name": "Sheinhardt Wig Company",
  "reply_to_address": "newsletter@sheinhardt.com",
  "sharing_networks": [
    "twitter",
    "facebook",
    "linkedin"
  ],
  "socials": [
    {
      "label": null,
      "type": "twitter",
      "url": "https://x.com/sheinhardt"
    }
  ],
  "subscription_confirmation_redirect_url": "https://example.com/confirmed",
  "subscription_redirect_url": "https://example.com/thanks",
  "theme_configuration": {
    "primary-color": "#0069FF"
  },
  "timezone": "America/New_York",
  "tint_color": "#0069FF",
  "username": "sheinhardt",
  "web_css": ".container { max-width: 800px; }"
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "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"
}

Body parameters

All parameters are optional unless explicitly specified.

announcement_bar_background_color

Type
string
Description

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

Example
"#FF6600"

announcement_bar_text

Type
string
Description

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

Example
"Subscribe to get 20% off your first order!"

announcement_bar_visibility

Type
NewsletterAnnouncementBarVisibility
Description

Controls who sees the announcement bar on your archive page.

Example
"everyone"

archive_theme

Type
NewsletterArchiveTheme
Description

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

Example
"modern"

auditing_mode

Type
NewsletterAuditingMode
Description

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

Example
"enabled"

css

Type
string
Description

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

Example
".header { color: #000; }"

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

Example
"Hi {{ subscriber.email }}, We're sorry to see you go!"

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

Example
"You've canceled your premium subscription to {{ 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.

Example
"modern"

custom_email_template

Type
string
Description

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

Example
"modern"

custom_expired_trial_notification_body

Type
string
Description

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

custom_expired_trial_notification_subject

Type
string
Description

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

custom_expired_trial_notification_template

Type
string
Description

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

Example
"modern"

custom_gift_subscription_email_body

Type
string
Description

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

custom_gift_subscription_email_subject

Type
string
Description

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

custom_gift_subscription_email_template

Type
string
Description

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

Example
"modern"

custom_gift_unsubscription_email_body

Type
string
Description

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

custom_gift_unsubscription_email_subject

Type
string
Description

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

custom_gift_unsubscription_email_template

Type
string
Description

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

Example
"modern"

custom_premium_confirmation_email_body

Type
string
Description

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

custom_premium_confirmation_email_subject

Type
string
Description

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

custom_premium_confirmation_email_template

Type
string
Description

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

Example
"modern"

custom_subscription_confirmation_email_subject

Type
string
Description

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

custom_subscription_confirmation_email_text

Type
string
Description

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

custom_subscription_confirmation_email_template

Type
string
Description

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

Example
"modern"

custom_subscription_confirmation_reminder_email_subject

Type
string
Description

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

custom_subscription_confirmation_reminder_email_text

Type
string
Description

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

custom_subscription_confirmed_email_subject

Type
string
Description

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

custom_subscription_confirmed_email_text

Type
string
Description

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

description

Type
string
Description

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

Example
"Stay up to date with the latest trends in wigs and hairpieces"

domain

Type
string
Description

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

Example
"sheinhardt.com"

email_address

Type
string
Description

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

Example
"newsletter@sheinhardt.com"

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.

Example
"mail.sheinhardt.com"

email_theme_configuration

Type
object
Description

A dictionary of CSS token overrides for the email theme.

Example
{ "primary-color": "#0069FF" }

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

Example
[ "archives", "portal", "surveys" ]
Type
string
Description

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

Example
"<p>Thanks for reading!</p>"

from_name

Type
string
Description

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

Example
"Sheinhardt Wig Company"
Type
string
Description

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

Example
"<p>Welcome to our newsletter!</p>"

icon

Type
string
Description

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

Example
"https://example.com/icon.png"

image

Type
string
Description

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

Example
"https://example.com/header.jpg"

locale

Type
NewsletterLocale
Description

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

Example
"en"

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

Example
{ "source": "my-app", "tier": "pro" }

name

Type
string
Description

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

Example
"Sheinhardt Wig Company"

reply_to_address

Type
string
Description

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

Example
"newsletter@sheinhardt.com"

sharing_networks

Type
array
Description

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

Example
[ "twitter", "facebook", "linkedin" ]

socials

Type
array
Description

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

Example
[ { "label": null, "type": "twitter", "url": "https://x.com/sheinhardt" } ]

subscription_confirmation_redirect_url

Type
string
Description

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

Example
"https://example.com/confirmed"

subscription_redirect_url

Type
string
Description

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

Example
"https://example.com/thanks"

template

Type
NewsletterEmailTemplate
Description

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

Example
"modern"

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.

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.

Example
{ "primary-color": "#0069FF" }

timezone

Type
string
Description

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

Example
"America/New_York"

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.

Example
"#0069FF"

username

Type
string
Description

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

Example
"sheinhardt"

web_css

Type
string
Description

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

Example
".container { max-width: 800px; }"