Creating an email

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/emails"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "subject": "The subject line for the email",
  "body": "This is an example of the body of an email."
}

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.

{
    "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",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "description": "",
    "email_type": "public",
    "featured": false,
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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
}

Body parameters

All parameters are optional unless explicitly specified.

attachments

Type

array

publish_date

Type

string

subject

Type

string · required

Example

"The subject line for the email"

slug

Type

string

description

Type

string

canonical_url

Type

string

image

Type

string

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:  or .

Example

"This is an example of the body of an email."

email_type

Type

EmailType

status

Type

EmailStatus

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

secondary_id

Type

integer

filters

Type

FilterGroup

commenting_mode

Type

EmailCommentingMode

related_email_ids

Type

array

featured

Type

boolean

Description

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

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.

Error codes

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

Error Code	Description
`body_invalid`	The email body provided is invalid or cannot be parsed.
`canonical_url_invalid`	The canonical URL provided is not a valid URL.
`email_duplicate`	An email with the same identifiers already exists.
`email_invalid`	The email is invalid.
`publish_date_invalid`	The publish date provided is not valid or is in an incorrect format.
`publish_date_missing`	A publish date is required but was not provided.
`slug_invalid`	The slug provided is invalid or already in use.
`status_invalid`	The status provided is not valid.
`subject_invalid`	The subject provided is invalid or missing.
`tag_invalid`	The tag provided is invalid or does not exist.

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/emails"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "subject": "The subject line for the email",
  "body": "This is an example of the body of an email."
}

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.

{
    "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",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "description": "",
    "email_type": "public",
    "featured": false,
    "filters": {
        "filters": [],
        "groups": [],
        "predicate": "and"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "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
}

Body parameters

All parameters are optional unless explicitly specified.

attachments

Type

array

publish_date

Type

string

subject

Type

string · required

Example

"The subject line for the email"

slug

Type

string

description

Type

string

canonical_url

Type

string

image

Type

string

body

Type

string

Description

Example

"This is an example of the body of an email."

email_type

Type

EmailType

status

Type

EmailStatus

metadata

Type

object

Description

secondary_id

Type

integer

filters

Type

FilterGroup

commenting_mode

Type

EmailCommentingMode

related_email_ids

Type

array

featured

Type

boolean

Description

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

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.

Error codes

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

Error Code	Description
`body_invalid`	The email body provided is invalid or cannot be parsed.
`canonical_url_invalid`	The canonical URL provided is not a valid URL.
`email_duplicate`	An email with the same identifiers already exists.
`email_invalid`	The email is invalid.
`publish_date_invalid`	The publish date provided is not valid or is in an incorrect format.
`publish_date_missing`	A publish date is required but was not provided.
`slug_invalid`	The slug provided is invalid or already in use.
`status_invalid`	The status provided is not valid.
`subject_invalid`	The subject provided is invalid or missing.
`tag_invalid`	The tag provided is invalid or does not exist.

Introduction

API recipes

Emails

Subscribers

Tags

Images

Attachments

Newsletters

Exports

Bulk actions

RSS feeds

Webhooks

Comments

Surveys

Coupons

Automations

Accounts

Notes

Prices

API Requests

Events

Ping

Changelog

Sample requests

Sample responses

Body parameters

attachments

publish_date

subject

slug

description

canonical_url

image

body

email_type

status

metadata

secondary_id

filters

commenting_mode

related_email_ids

featured

should_trigger_pay_per_email_billing

Error codes

Creating an email

Sample requests

Sample responses

Body parameters

attachments

publish_date

subject

slug

description

canonical_url

image

body

email_type

status

metadata

secondary_id

filters

commenting_mode

related_email_ids

featured

should_trigger_pay_per_email_billing

Error codes