Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

Introduction

Emails are why you're here on Buttondown, right? Creating an email via the API is just like creating one in the interface; it will instantly trigger sending actual emails, based on the tags and email type you provide.

Relevant changes to the schema:

  • 2024-08-15: unshipped the included_tags and excluded_tags fields.
  • 2024-12-30: unshipped the is_comments_disabled field, and replaced it with a more flexible commenting_mode field.
{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "modification_date": "2000-01-01T00:00:00+00:00",
    "publish_date": "2000-01-01T00:00:00+00:00",
    "subject": "Welcome to the newsletter",
    "body": "I hope you really enjoy it!",
    "status": "sent",
    "slug": "welcome-to-the-newsletter",
    "canonical_url": "",
    "email_type": "public",
    "image": "",
    "description": "",
    "metadata": {},
    "source": "app",
    "secondary_id": null,
    "commenting_mode": "enabled",
    "absolute_url": "http://127.0.0.1:8000/sheinhardt/archive/welcome-to-the-newsletter/",
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "analytics": null,
    "template": null,
    "attachments": [],
    "related_email_ids": [],
    "featured": false
}

Fields

id

Type
string
Description

The unique identifier for the email.

creation_date

Type
string
Description

The date and time at which the object was first created.

modification_date

Type
string
Description

The date and time at which the object was last modified.

publish_date

Type
string
Description

The date and time at which the email should be published in the future (for scheduled emails), or the date and time at which the email was published (for sent emails).

subject

Type
string
Description

The subject line for the email.

body

Type
string
Description

The body of the email. Can be either HTML or markdown.

status

Type
EmailStatus
Description

The current status of the email.

slug

Type
string
Description

A short, human-readable identifier for the email. (Used in the URL of the email, and in the 'slug' field of the email object.)

canonical_url

Type
string
Description

The URL of the original source of the content.

email_type

Type
EmailType

image

Type
string
Description

A primary image to be used when previewing the email on the web or in other contexts.

description

Type
string
Description

A human-readable description of the email, used for archives and SEO.

metadata

Type
object
Description

A structured key-value blob that you can use to store arbitrary data on the object.

source

Type
EmailSource
Description

The source of the email.

secondary_id

Type
integer
Description

An informal 'number' for the email, used in some templates ('This was issue #123').

commenting_mode

Type
EmailCommentingMode

absolute_url

Type
string

filters

Type
FilterGroup

analytics

Type
Analytics

template

Type
NewsletterEmailTemplate
Description

If present, this template overrides your newsletter's default template.

attachments

Type
array
Description

A list of attachment IDs present on the email. (See Attachments for more information.)

Type
array
Description

A list of email IDs that are related to this email. Related emails are shown at the bottom of the email and archive pages.

Type
boolean
Description

Designated whether or not this email should be highlighted within the archives. (Currently unused.)

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook