Buttondown

{
  "type": "object",
  "title": "Analytics",
  "required": [
    "recipients",
    "deliveries",
    "opens",
    "clicks",
    "temporary_failures",
    "permanent_failures",
    "unsubscriptions",
    "complaints"
  ],
  "properties": {
    "opens": {
      "type": "integer",
      "title": "Opens"
    },
    "clicks": {
      "type": "integer",
      "title": "Clicks"
    },
    "complaints": {
      "type": "integer",
      "title": "Complaints"
    },
    "deliveries": {
      "type": "integer",
      "title": "Deliveries"
    },
    "recipients": {
      "type": "integer",
      "title": "Recipients"
    },
    "unsubscriptions": {
      "type": "integer",
      "title": "Unsubscriptions"
    },
    "permanent_failures": {
      "type": "integer",
      "title": "Permanent Failures"
    },
    "temporary_failures": {
      "type": "integer",
      "title": "Temporary Failures"
    }
  }
}

{
  "type": "object",
  "title": "BulkAction",
  "required": [
    "id",
    "creation_date",
    "status",
    "type",
    "metadata"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "type": {
      "$ref": "#/components/schemas/BulkActionType"
    },
    "status": {
      "$ref": "#/components/schemas/BulkActionStatus"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "object"
          }
        ]
      }
    },
    "creation_date": {
      "type": "string",
      "title": "Creation Date",
      "format": "date-time"
    },
    "completion_date": {
      "type": "string",
      "title": "Completion Date",
      "format": "date-time"
    }
  },
  "description": "A bulk action represents, well, a bulk action. It is used to perform\nactions on a large number of objects at once. For example, you can\nuse it to delete a large number of emails, or to unsubscribe a large\nnumber of subscribers. The actions within a bulk action are processed\nserially by Buttondown; this should be considered an ergonomic way to\nbatch API calls across the network rather than a net-new piece of functionality\nin of itself."
}

{
  "type": "object",
  "title": "BulkActionInput",
  "required": [
    "type",
    "metadata"
  ],
  "properties": {
    "type": {
      "$ref": "#/components/schemas/BulkActionType"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "object"
          }
        ]
      }
    }
  }
}

{
  "enum": [
    "not_started",
    "in_progress",
    "processed",
    "failed"
  ],
  "type": "string",
  "title": "Status",
  "description": "\n        Represents the status of a bulk action.\n\n        No action is required to move from one state or another; Buttondown\n        internally handles the transitions, and exposing the status is for\n        observability purposes only.\n        "
}

{
  "enum": [
    "apply_tags",
    "apply_metadata",
    "ban_subscribers",
    "delete_emails",
    "delete_subscribers",
    "delete_tags",
    "reactivate_subscribers",
    "replay_events",
    "resubscribe_subscribers",
    "send_emails",
    "send_reminders",
    "update_email_types",
    "unsubscribe_subscribers"
  ],
  "type": "string",
  "title": "Type",
  "description": "\n        Represents the action being performed on a bulk of objects.\n\n        (Not to be coy, but these names should be self-explanatory.)\n        "
}

{
  "enum": [
    "username_already_exists"
  ],
  "type": "string",
  "title": "CreateNewsletterErrorCode",
  "description": "\n    Represents the type of error that occurred when creating a newsletter.\n\n    Human-readable error messages are provided in the `detail` field of the response;\n    these values are meant to be parseable by code or client logic.\n    "
}

{
  "type": "object",
  "title": "Email",
  "required": [
    "id",
    "subject",
    "body",
    "email_type",
    "slug",
    "external_url",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "body": {
      "type": "string",
      "title": "Body"
    },
    "slug": {
      "type": "string",
      "title": "Slug"
    },
    "status": {
      "$ref": "#/components/schemas/EmailStatus"
    },
    "subject": {
      "type": "string",
      "title": "Subject"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    },
    "email_type": {
      "$ref": "#/components/schemas/EmailType"
    },
    "external_url": {
      "type": "string",
      "title": "External Url"
    },
    "publish_date": {
      "type": "string",
      "title": "Publish Date",
      "format": "date-time"
    },
    "secondary_id": {
      "type": "integer",
      "title": "Secondary Id"
    },
    "excluded_tags": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "title": "Excluded Tags"
    },
    "included_tags": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "title": "Included Tags"
    }
  },
  "description": "Emails are what you're for here on Buttondown at the end of the day, right?\nCreating an email via the API is just like creating one in the interface;\nit will instantly trigger sending actual emails,\nbased on the tags and email type you provide."
}

{
  "enum": [
    "subject_invalid",
    "email_duplicate",
    "email_invalid"
  ],
  "type": "string",
  "title": "EmailCreationErrorCode",
  "description": "\n    Represents the type of error that occurred when creating an email.\n\n    Human-readable error messages are provided in the `detail` field of the response;\n    these values are meant to be parseable by code or client logic.\n    "
}

{
  "type": "object",
  "title": "EmailInput",
  "required": [
    "subject"
  ],
  "properties": {
    "body": {
      "type": "string",
      "title": "Body",
      "default": ""
    },
    "status": {
      "$ref": "#/components/schemas/EmailStatus"
    },
    "subject": {
      "type": "string",
      "title": "Subject"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    },
    "email_type": {
      "$ref": "#/components/schemas/EmailType"
    },
    "publish_date": {
      "type": "string",
      "title": "Publish Date",
      "format": "date-time"
    },
    "excluded_tags": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "format": "uuid"
          },
          {
            "type": "string"
          }
        ]
      },
      "title": "Excluded Tags",
      "default": []
    },
    "included_tags": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "format": "uuid"
          },
          {
            "type": "string"
          }
        ]
      },
      "title": "Included Tags",
      "default": []
    }
  },
  "x-konfig-properties": {
    "status": {
      "default": "about_to_send"
    },
    "email_type": {
      "default": "public"
    }
  }
}

{
  "enum": [
    "draft",
    "about_to_send",
    "scheduled",
    "in_flight",
    "deleted",
    "errored",
    "sent",
    "imported"
  ],
  "type": "string",
  "title": "Status",
  "description": "\n        Represents the state of an email.\n\n        No action is required to move from one state or another; Buttondown\n        internally handles the transitions, and exposing the status is for\n        observability purposes only.\n        "
}

{
  "enum": [
    "public",
    "private",
    "premium",
    "free",
    "archival",
    "hidden"
  ],
  "type": "string",
  "title": "Type",
  "description": "\n        Represents the audience of an email, and to whom it is visible both in the initial\n        email and in online archives.\n        "
}

{
  "type": "object",
  "title": "ErrorMessage",
  "required": [
    "detail"
  ],
  "properties": {
    "code": {
      "title": "Code"
    },
    "detail": {
      "type": "string",
      "title": "Detail"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "title": "ErrorMessage[CreateNewsletterErrorCode]",
  "required": [
    "code",
    "detail"
  ],
  "properties": {
    "code": {
      "$ref": "#/components/schemas/CreateNewsletterErrorCode"
    },
    "detail": {
      "type": "string",
      "title": "Detail"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "title": "ErrorMessage[EmailCreationErrorCode]",
  "required": [
    "code",
    "detail"
  ],
  "properties": {
    "code": {
      "$ref": "#/components/schemas/EmailCreationErrorCode"
    },
    "detail": {
      "type": "string",
      "title": "Detail"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "title": "ErrorMessage[ListSubscribersErrorCode]",
  "required": [
    "code",
    "detail"
  ],
  "properties": {
    "code": {
      "$ref": "#/components/schemas/ListSubscribersErrorCode"
    },
    "detail": {
      "type": "string",
      "title": "Detail"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "title": "ErrorMessage[UpdateSubscriberErrorCode]",
  "required": [
    "code",
    "detail"
  ],
  "properties": {
    "code": {
      "$ref": "#/components/schemas/UpdateSubscriberErrorCode"
    },
    "detail": {
      "type": "string",
      "title": "Detail"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "title": "ErrorMessage[UpdateTagErrorCode]",
  "required": [
    "code",
    "detail"
  ],
  "properties": {
    "code": {
      "$ref": "#/components/schemas/UpdateTagErrorCode"
    },
    "detail": {
      "type": "string",
      "title": "Detail"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {},
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "title": "Export",
  "required": [
    "id",
    "creation_date",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "url": {
      "type": "string",
      "title": "Url"
    },
    "status": {
      "$ref": "#/components/schemas/ExportStatus"
    },
    "creation_date": {
      "type": "string",
      "title": "Creation Date",
      "format": "date-time"
    },
    "completion_date": {
      "type": "string",
      "title": "Completion Date",
      "format": "date-time"
    }
  },
  "description": "Some software applications may want programmatic access to their newsletter exports.\nThis assists with a few niche use cases, such as regular backups or data ingestion\n(into a data warehouse), or post-publishing processes that hinge on email events.\n\nIn general, you probably won't _need_ to use this endpoint unless you\n _absolutely_ need to use this endpoint."
}

{
  "enum": [
    "subscribers",
    "emails",
    "scheduled_emails",
    "drafts",
    "unsubscribers",
    "events",
    "referrals"
  ],
  "type": "string",
  "title": "Collection",
  "description": "\n        A group of data that can be exported in an export.\n        "
}

{
  "type": "object",
  "title": "ExportInput",
  "required": [
    "collections"
  ],
  "properties": {
    "collections": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ExportCollection"
      }
    }
  }
}

{
  "enum": [
    "error",
    "in_progress",
    "not_started",
    "ready"
  ],
  "type": "string",
  "title": "Status",
  "description": "\n        Represents the status of an export.\n\n        No action is required to move from one state or another; Buttondown\n        internally handles the transitions, and exposing the status is for\n        observability purposes only.\n        "
}

{
  "type": "object",
  "title": "Image",
  "required": [
    "id",
    "creation_date",
    "image"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "image": {
      "type": "string",
      "title": "Image"
    },
    "creation_date": {
      "type": "string",
      "title": "Creation Date",
      "format": "date-time"
    }
  },
  "description": "Images are, well, images! Buttondown allows you to upload images to its secure\nS3 bucket and do with them what you will. This is sort of an odd duck of an\nAPI, to be sure, but if you want to be able to do things like draft\nand send emails completely on your iPad you need a surefire way of creating images."
}

{
  "type": "object",
  "title": "FileParams",
  "required": [
    "image"
  ],
  "properties": {
    "image": {
      "type": "string",
      "title": "Image",
      "format": "binary"
    }
  }
}

{
  "enum": [
    "invalid_tag"
  ],
  "type": "string",
  "title": "ListSubscribersErrorCode",
  "description": "\n    Represents the type of error that occurred when listing subscribers.\n\n    Human-readable error messages are provided in the `detail` field of the response;\n    these values are meant to be parseable by code or client logic.\n    "
}

{
  "type": "object",
  "title": "Newsletter",
  "required": [
    "id",
    "username",
    "name",
    "description",
    "creation_date",
    "api_key"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "api_key": {
      "type": "string",
      "title": "Api Key",
      "format": "uuid"
    },
    "username": {
      "type": "string",
      "title": "Username"
    },
    "description": {
      "type": "string",
      "title": "Description"
    },
    "creation_date": {
      "type": "string",
      "title": "Creation Date",
      "format": "date-time"
    }
  },
  "description": "You will likely not need to interact with your newsletter settings\nprogrammatically, but if you do, this is the endpoint for you. You can\ncreate, update, and list newsletters via the API; this is ideal for\nintegrating with Buttondown as a headless email or newsletter provider\n(e.g. for a SaaS product.)"
}

{
  "type": "object",
  "title": "NewsletterInput",
  "required": [
    "username",
    "name",
    "description"
  ],
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "username": {
      "type": "string",
      "title": "Username"
    },
    "description": {
      "type": "string",
      "title": "Description"
    }
  }
}

{
  "type": "object",
  "title": "NewsletterUpdateInput",
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "username": {
      "type": "string",
      "title": "Username"
    },
    "description": {
      "type": "string",
      "title": "Description"
    }
  }
}

{
  "type": "object",
  "title": "Page[Email]",
  "required": [
    "results",
    "count"
  ],
  "properties": {
    "next": {
      "type": "string",
      "title": "Next"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Email"
      },
      "title": "Results"
    },
    "previous": {
      "type": "string",
      "title": "Previous"
    }
  }
}

{
  "type": "object",
  "title": "Page[Export]",
  "required": [
    "results",
    "count"
  ],
  "properties": {
    "next": {
      "type": "string",
      "title": "Next"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Export"
      },
      "title": "Results"
    },
    "previous": {
      "type": "string",
      "title": "Previous"
    }
  }
}

{
  "type": "object",
  "title": "Page[Newsletter]",
  "required": [
    "results",
    "count"
  ],
  "properties": {
    "next": {
      "type": "string",
      "title": "Next"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Newsletter"
      },
      "title": "Results"
    },
    "previous": {
      "type": "string",
      "title": "Previous"
    }
  }
}

{
  "type": "object",
  "title": "Page[Subscriber]",
  "required": [
    "results",
    "count"
  ],
  "properties": {
    "next": {
      "type": "string",
      "title": "Next"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Subscriber"
      },
      "title": "Results"
    },
    "previous": {
      "type": "string",
      "title": "Previous"
    }
  }
}

{
  "type": "object",
  "title": "Page[Tag]",
  "required": [
    "results",
    "count"
  ],
  "properties": {
    "next": {
      "type": "string",
      "title": "Next"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Tag"
      },
      "title": "Results"
    },
    "previous": {
      "type": "string",
      "title": "Previous"
    }
  }
}

{
  "type": "object",
  "title": "Subscriber",
  "required": [
    "id",
    "email",
    "creation_date",
    "secondary_id",
    "subscriber_type",
    "source",
    "utm_campaign",
    "utm_medium",
    "utm_source"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "title": "Tags",
      "default": []
    },
    "email": {
      "type": "string",
      "title": "Email"
    },
    "notes": {
      "type": "string",
      "title": "Notes",
      "default": ""
    },
    "source": {
      "$ref": "#/components/schemas/SubscriberSource"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {}
    },
    "utm_medium": {
      "type": "string",
      "title": "Utm Medium"
    },
    "utm_source": {
      "type": "string",
      "title": "Utm Source"
    },
    "referrer_url": {
      "type": "string",
      "title": "Referrer Url",
      "default": ""
    },
    "secondary_id": {
      "type": "integer",
      "title": "Secondary Id"
    },
    "utm_campaign": {
      "type": "string",
      "title": "Utm Campaign"
    },
    "creation_date": {
      "type": "string",
      "title": "Creation Date",
      "format": "date-time"
    },
    "subscriber_type": {
      "$ref": "#/components/schemas/SubscriberType"
    }
  },
  "description": "Subscribers are the main way you collect email addresses and\nrecipients on Buttondown. They're what you see on your\n[subscribers page](https://buttondown.email/subscribers)."
}

{
  "type": "object",
  "title": "SubscriberInput",
  "required": [
    "email"
  ],
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "title": "Tags",
      "default": []
    },
    "email": {
      "type": "string",
      "title": "Email"
    },
    "notes": {
      "type": "string",
      "title": "Notes",
      "default": ""
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "default": {}
    },
    "referrer_url": {
      "type": "string",
      "title": "Referrer Url",
      "default": ""
    }
  }
}

{
  "enum": [
    "api",
    "import",
    "organic",
    "user",
    "admin"
  ],
  "type": "string",
  "title": "Source",
  "description": "\n        Represents the original provenance of a subscriber. This value is not exposed\n        to subscribers; it's only used for internal tracking purposes and governs some\n        of the behavior of the subscriber (i.e. whether or not to require double\n        opt-in.)\n        "
}

{
  "enum": [
    "regular",
    "premium",
    "churning",
    "past_due",
    "gifted",
    "unpaid",
    "unactivated",
    "unsubscribed",
    "spammy",
    "removed",
    "trialed",
    "disabled",
    "paused"
  ],
  "type": "string",
  "title": "Type",
  "description": "\n        Represents the state of a subscriber and what emails they\n        should or should not be receiving. This type is meant to be fully expressive\n        so as to consolidate the logic of determining what emails a subscriber should\n        receive into a single place.\n        "
}

{
  "type": "object",
  "title": "SubscriberUpdateInput",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "title": "Tags"
    },
    "email": {
      "type": "string",
      "title": "Email"
    },
    "notes": {
      "type": "string",
      "title": "Notes"
    },
    "metadata": {
      "type": "object",
      "title": "Metadata"
    },
    "referrer_url": {
      "type": "string",
      "title": "Referrer Url",
      "default": ""
    },
    "subscriber_type": {
      "$ref": "#/components/schemas/SubscriberType"
    }
  }
}

{
  "type": "object",
  "title": "Tag",
  "required": [
    "id",
    "name",
    "color",
    "secondary_id",
    "creation_date"
  ],
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "color": {
      "type": "string",
      "title": "Color"
    },
    "description": {
      "type": "string",
      "title": "Description"
    },
    "secondary_id": {
      "type": "integer",
      "title": "Secondary Id"
    },
    "creation_date": {
      "type": "string",
      "title": "Creation Date",
      "format": "date-time"
    }
  },
  "description": "Tags are a way to organize your subscribers. You can create, update, and\ndelete tags via the API. You can also list all tags for a given newsletter.\n\nTags don't have any strict functionality on their own, but you can send emails\nto subscribers with a given tag (or to all subscribers _without_ a given tag.)"
}

{
  "type": "object",
  "title": "TagInput",
  "required": [
    "name",
    "color"
  ],
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "color": {
      "type": "string",
      "title": "Color"
    },
    "description": {
      "type": "string",
      "title": "Description"
    }
  }
}

{
  "type": "object",
  "title": "TagUpdateInput",
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "color": {
      "type": "string",
      "title": "Color"
    },
    "description": {
      "type": "string",
      "title": "Description"
    }
  }
}

{
  "enum": [
    "email_already_exists",
    "email_invalid",
    "subscriber_type_invalid"
  ],
  "type": "string",
  "title": "UpdateSubscriberErrorCode",
  "description": "\n    Represents the type of error that occurred when updating a subscriber.\n\n    Human-readable error messages are provided in the `detail` field of the response;\n    these values are meant to be parseable by code or client logic.\n    "
}

{
  "enum": [
    "name_already_exists"
  ],
  "type": "string",
  "title": "UpdateTagErrorCode",
  "description": "\n    A potential error code that can be returned when updating a tag.\n    "
}