Buttondown logo

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.
  • 2025-09-23: increased the maximum length of the subject field from 1000 to 2000 characters.
{
    "id": "em_29fxqcmrkp969vzttksexvmvr8",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "absolute_url": "http://127.0.0.1:8000/sheinhardt/archive/welcome-to-the-newsletter/",
    "analytics": null,
    "attachments": [],
    "body": "I hope you really enjoy it!",
    "canonical_url": "",
    "commenting_mode": "enabled",
    "review_mode": "disabled",
    "description": "",
    "email_type": "public",
    "featured": false,
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "image": "",
    "metadata": {},
    "modification_date": "2000-01-01T00:00:00+00:00",
    "publish_date": "2000-01-01T00:00:00+00:00",
    "related_email_ids": [],
    "secondary_id": null,
    "should_trigger_pay_per_email_billing": false,
    "slug": "welcome-to-the-newsletter",
    "source": "app",
    "status": "sent",
    "subject": "Welcome to the newsletter",
    "suppression_reason": null,
    "template": null
}

Fields

id

Type
string
Description

A unique TypeID associated with the object.

creation_date

Type
string
Description

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

absolute_url

Type
string

analytics

Type
Analytics

attachments

Type
Description

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

body

Type
string
Description

The body of the email, in either HTML or markdown format. Buttondown attempts to intelligently detect the format of the body automatically, but you can also specify the format explicitly by prepending the text with the buttondown-editor-mode comment: <!-- buttondown-editor-mode: fancy --> or <!-- buttondown-editor-mode: plaintext -->.

canonical_url

Type
string
Description

The URL of the original source of the content.

commenting_mode

Type
EmailCommentingMode

review_mode

Type
Description

The draft review mode for the email. Use unlisted to allow draft comments via link, or disabled to turn draft comments off.

description

Type
string
Description

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

email_type

Type
EmailType
Description

The type of email.

Type
boolean
Description

Designated whether or not this email should be highlighted within the archives.

filters

Type
FilterGroup

image

Type
string
Description

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

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

modification_date

Type
string
Description

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

publish_date

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

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.

secondary_id

Type
Description

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

should_trigger_pay_per_email_billing

Type
boolean
Description

Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate between free updates and premium newsletters.

slug

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

source

Type
EmailSource
Description

The source of the email.

status

Type
EmailStatus
Description

The current status of the email.

subject

Type
string
Description

The subject line for the email.

suppression_reason

Type
EmailSuppressionReason
Description

Reason for suppression, if email is suppressed.

template

Type
NewsletterEmailTemplate
Description

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