Buttondown logo

IntroductionStatusesSourcesAudiencesAnalyticsTemplatesCommenting modesSuppression reason

Audience filters

IntroductionFilteringOperators

Routes

Creating an emailListing emailsRetrieving emailUpdating an emailDeleting an emailRetrieving email analyticsSending a draft emailListing email eventsRetrieving email historyRetrieving an email's historical body

Buttondown logo

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: <!-- buttondown-editor-mode: fancy --> or <!-- buttondown-editor-mode: plaintext -->.

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
Type
array
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 CodeDescription
body_invalidThe email body provided is invalid or cannot be parsed.
canonical_url_invalidThe canonical URL provided is not a valid URL.
email_duplicateAn email with the same identifiers already exists.
email_invalidThe email is invalid.
publish_date_invalidThe publish date provided is not valid or is in an incorrect format.
publish_date_missingA publish date is required but was not provided.
slug_invalidThe slug provided is invalid or already in use.
status_invalidThe status provided is not valid.
subject_invalidThe subject provided is invalid or missing.
tag_invalidThe tag provided is invalid or does not exist.