v4

latestOpenAPI 3.1.0MIT2026-08-02128224900.7 KB

Newsletters

Retrieve Newsletter

Retrieve a specific newsletter by its ID

get/newsletters/{id}

Path parameters

idstring required

Response

idstring required

A unique TypeID associated with the object.

creation_datestring date-time required

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_visibility'disabled' | 'everyone' | 'free_only' | 'logged_out_only' | 'paid_only'

An enumeration.

api_keystring uuid required

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

archive_theme'classic' | 'modern' | 'arbus' | 'lovelace' | 'myrna'

An enumeration.

auditing_mode'disabled' | 'enabled' | 'aggressive' nullable

An enumeration.

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_template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

custom_email_templatestring nullable

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_expired_trial_notification_template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

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_template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

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_template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

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_template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

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_template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

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 required

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.

email_theme_configurationobject

A dictionary of CSS token overrides for the email theme.

enabled_featuresstring[]

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_status'none' | 'invalid' | 'valid'

The DNS verification status of a newsletter's custom hosting domain.

iconstring nullable

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 nullable

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

locale'cs-CZ' | 'nl-NL' | 'en-AU' | 'en-CA' | 'en-GB' | 'en' | 'et' | 'fi-FI' | 'fr' | 'de' | 'it' | 'ja-JP' | 'ne' | 'nb-NO' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru' | 'es' | 'tr' | 'sv-SE'

An enumeration.

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 required

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.

The DNS verification status of a newsletter's custom sending domain.

sharing_networksstring[]

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

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

template'classic' | 'custom' | 'modern' | 'plaintext' | 'naked'

Represents the template of an email.

Each template has a different layout/style; you can view screenshots and examples in the docs.

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 required

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