Buttondown logo

IntroductionAuditing modes

Routes

Listing newslettersCreating a newsletterUpdating a newsletterDeleting a newsletter

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 = {
  "auditing_mode": "enabled",
  "css": ".header { color: #000; }",
  "css_tokens": {
    "primary-color": "#0069FF"
  },
  "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",
  "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",
  "name": "Sheinhardt Wig Company",
  "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.

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

css_tokens

Type
object
Description

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

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

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"

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"

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"

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.

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

Error codes

This endpoint may return the following error codes. See the error codes reference for more details about error handling.

Error CodeDescription
username_already_existsA newsletter already exists with that username.
username_malformedThe username is malformed.