Buttondown logo

Creating a note

Notes consist of two things:

  1. A body, which is the text content of the note.
  2. Metadata, which is a structured key-value blob that you can use to store arbitrary data on the object.
  3. A reference to the object the note is attached to, which consists of a model_type and a model_id. Model types are as follows:
model_typeDescriptionRelated model
automationAn automation workflowAutomation
emailEmail messageEmail
external_feedExternal feed (e.g., RSS source)ExternalFeed
stripe_customerStripe customer recordStripeCustomer
subscriberA subscriber to your newsletterSubscriber
surveyA surveySurvey
tagSubscriber tagSubscriberTag

By creating a note programmatically, you can unlock a lot of interesting use cases and functionality. Here are some examples:

  1. Add a note to a given subscriber whenever they upgrade or churn from a paid plan.
  2. Add notes to emails when you mutate them with new data for provenance tracking.

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/notes"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "body": "This subscriber upgraded to a paid plan.",
  "model_type": "email",
  "model_id": "13121cd6-0dfc-424c-bb12-988b0a32fcb3"
}

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.

{
    "id": "note_29fxqcmrkp969vzttksexvmvr8",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "body": "This person rocks :)",
    "model_type": "subscriber",
    "model_id": "sub_0k28edc3fw896bp4mrhc535z5k",
    "metadata": {},
    "source": "user",
    "user_id": "acc_6d9ps3y19d89d8wpvkwme1s6w5",
    "user": null
}

Body parameters

All parameters are optional unless explicitly specified.

body

Type
string · required
Description

The text content of the note.

Example
"This subscriber upgraded to a paid plan."

model_type

Type
string · required
Description

The type of object this note is attached to (e.g., 'email', 'subscriber').

Example
"email"

model_id

Type
string · required
Description

The ID of the object this note is attached to.

Example
"13121cd6-0dfc-424c-bb12-988b0a32fcb3"

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