Buttondown logo

Creating a newsletter

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/newsletters"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "announcement_bar_background_color": "#FF6600",
  "announcement_bar_text": "Subscribe to get 20% off your first order!",
  "announcement_bar_visibility": "everyone",
  "archive_theme": "modern",
  "auditing_mode": "enabled",
  "css": ".header { color: #000; }",
  "custom_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",
  "locale": "en",
  "name": "Sheinhardt Wig Company",
  "reply_to_address": "newsletter@sheinhardt.com",
  "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",
  "template": "modern",
  "theme_configuration": {
    "primary-color": "#0069FF"
  },
  "timezone": "America/New_York",
  "tint_color": "#0069FF",
  "username": "sheinhardt",
  "web_css": ".container { max-width: 800px; }"
}

response = requests.request("POST", 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_email_template

Type
string
Description

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

Example
"modern"

description

Type
string · required
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.)

name

Type
string · required
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"

socials

Type
[]
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 · required
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; }"