--- title: "List Newsletters" method: GET path: "/newsletters" tags: ["Newsletters"] --- # List Newsletters `GET /newsletters` List all newsletters ## Query parameters - `page` integer — The page number of the paginated response. ## Response `200` OK - NewsletterPage - `results` Newsletter[], required — The list of results for this page. - `id` string, required — A unique TypeID associated with the object. - `creation_date` string, date-time, required — The date and time at which the object was first created. - `announcement_bar_background_color` string — The background color for the announcement bar on your archive page. Must be a valid hex color code. - `announcement_bar_text` string — 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_key` string, 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. - `css` string — Custom CSS styling applied to your newsletter emails. See [CSS customization](https://docs.buttondown.com/customizing-email-design#adding-custom-css) for more information. - `custom_churn_email_body` string — Custom body content for the email sent when a paid subscriber cancels. Supports template tags like `{{ subscriber.email }}` and `{{ newsletter.name }}`. - `custom_churn_email_subject` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `custom_email_template` string, nullable — The identifier for a custom email template. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options. - `custom_expired_trial_notification_body` string — Custom body content for the email sent when a subscriber's free trial expires. Supports template tags. - `custom_expired_trial_notification_subject` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `custom_gift_subscription_email_body` string — Custom body content for the email sent when someone receives a gift subscription. Supports template tags. - `custom_gift_subscription_email_subject` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `custom_gift_unsubscription_email_body` string — Custom body content for the email sent when a gift subscription ends. Supports template tags. - `custom_gift_unsubscription_email_subject` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `custom_premium_confirmation_email_body` string — Custom body content for the email sent when a subscriber upgrades to a paid plan. Supports template tags. - `custom_premium_confirmation_email_subject` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `custom_subscription_confirmation_email_subject` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `custom_subscription_confirmation_email_text` string — 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_subject` string — Custom subject line for the reminder email sent to subscribers who haven't confirmed. Supports template tags. - `custom_subscription_confirmation_reminder_email_text` string — Custom body content for the reminder email sent to subscribers who haven't confirmed. Supports template tags. - `custom_subscription_confirmed_email_subject` string — Custom subject line for the email sent after a subscriber confirms their subscription. Supports template tags. - `custom_subscription_confirmed_email_text` string — Custom body content for the email sent after a subscriber confirms their subscription. Supports template tags. - `description` string, required — A brief description of your newsletter, displayed on your public archive page and used for SEO. - `domain` string — The custom domain where your newsletter archives are hosted (e.g., 'newsletter.example.com'). See [custom domains](https://docs.buttondown.com/hosting-on-a-custom-domain) for setup instructions. - `email_address` string — The 'From' email address used when sending your newsletter. Must be verified before use. - `email_domain` string — The custom domain from which your newsletter emails are sent (e.g., 'mail.example.com'). See [sending domains](https://docs.buttondown.com/sending-from-a-custom-domain) for setup instructions. - `email_theme_configuration` object — A dictionary of CSS token overrides for the email theme. - `enabled_features` string[] — A list of features enabled for your newsletter. Common values include 'archives', 'portal', 'surveys', 'comments', 'paid_subscriptions', 'automations', 'webhooks', 'tracking', and 'referrals'. - `footer` string — HTML content displayed at the bottom of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags). - `from_name` string — The display name shown in the 'From' field of your emails (e.g., 'Jane from Acme Newsletter'). - `header` string — HTML content displayed at the top of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags). - `hosting_domain_status` 'none' | 'invalid' | 'valid' — The DNS verification status of a newsletter's custom hosting domain. - `icon` string, nullable — URL to your newsletter's icon image, used as a favicon and in various UI contexts. - `icon_alt_text` string — Alt text for the newsletter icon, used by screen readers and shown when the image cannot load. - `image` string, 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. - `metadata` object — 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.](https://docs.buttondown.com/metadata)) - `name` string, required — The display name of your newsletter, shown to subscribers and on your archive page. - `reply_to_address` string — An alternative email address that receives replies to your newsletter emails, instead of the sending address. - `sending_domain_status` 'none' | 'invalid' | 'awaiting_ssl' | 'failing' | 'deliberately_cold' | 'valid' — The DNS verification status of a newsletter's custom sending domain. - `sharing_networks` string[] — A list of social networks to show share buttons for on your archive pages. - `socials` SocialAccountSchema[] — A list of social media accounts linked to your newsletter, displayed on your archive page. Each entry has a `type`, `url`, and optional `label`. - `type` 'generic' | 'ao3' | 'arena' | 'bandcamp' | 'behance' | 'bluesky' | 'bookbub' | 'bookshop' | 'discord' | 'etsy' | 'facebook' | 'github' | 'goodreads' | 'gumroad' | 'instagram' | 'itchio' | 'kofi' | 'letterboxd' | 'linkedin' | 'linktree' | 'mastodon' | 'medium' | 'patreon' | 'pinterest' | 'reddit' | 'soundcloud' | 'spotify' | 'steam' | 'substack' | 'telegram' | 'threads' | 'tiktok' | 'tumblr' | 'twitch' | 'twitter' | 'vimeo' | 'youtube', required — An enumeration. - `url` string, required — The URL of the social media profile. - `label` string, nullable — An optional display label for the social media account. - `sort` string — The default sorting method for listing subscribers or messages. Example values: 'creation_date', '-creation_date', 'email_address'. - `subscription_confirmation_redirect_url` string — A URL to redirect subscribers to after they confirm their subscription via double opt-in. - `subscription_redirect_url` string — 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](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates). - `test_mode` boolean — Whether test mode is enabled. When enabled, emails are not actually sent to subscribers, useful for testing automations and workflows. - `theme_configuration` object — Custom theme configuration (variables) for your newsletter. These can be referenced in your CSS and templates to maintain consistent styling. - `timezone` string — The timezone used for scheduling and displaying dates in your newsletter (e.g., 'America/New_York', 'Europe/London'). - `tint_color` string — 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. - `username` string, required — The unique URL-safe identifier for your newsletter, used in your archive URL (e.g., 'buttondown.com/username'). - `web_css` string — Custom CSS styling applied to your newsletter's web presence (archive pages, subscription forms, etc.). - `next` string, nullable — The URL to the next page of results, if any. - `previous` string, nullable — The URL to the previous page of results, if any. - `count` integer, required — The total number of results across all pages. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `429` — Too Many Requests --- [API](https://skmtc.net/buttondown/apis/buttondown-api.md) · [All operations](https://skmtc.net/buttondown/apis/buttondown-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/buttondown/buttondown-api/revisions/0c0c3e81fc96/schema)