API reference

Brands

5 operations.

GET /v1/brands

The account's brands, the default first, then by name.

Operation id
listBrands
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
account.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Answers

200 The brands. application/json

Field Type Always sent Notes
brands array of object yes
brands[] object yes
brands[].id string yes
brands[].name string yes
brands[].is_default boolean yes The brand of every event type that names none. An account with brands has one.
brands[].primary_color string yes
brands[].accent_color string or null yes
brands[].sender_name string or null yes The name emails are sent under. Null: the account's name. The address stays ours.
brands[].reply_to_email string or null yes Where a visitor's reply goes. Null: the host's own address.
brands[].version integer yes
brands[].created_at string yes Limits: format date-time.
brands[].updated_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
429 Too many attempts. rate_limited

POST /v1/brands

Adds a brand. The account's first brand is its default. A primary colour the palette rule refuses is refused, with the nearest colour that passes.

Operation id
createBrand
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
account.update
Retry key
Required: send an Idempotency-Key header.
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
Idempotency-Key header string yes Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
name string yes
primary_color string yes #rrggbb. Refused when it is under 3:1 against white or the page background, or when neither white nor dark text reaches 4.5:1 on it; the refusal names the nearest colour that passes.
accent_color string or null no #rrggbb. Tints the selected day and time. Null: a tint of the primary.
sender_name string or null no
reply_to_email string or null no
is_default boolean no Make it the default; the old default stops being it. The account's first brand is the default anyway.

Answers

201 The brand. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
name string yes
is_default boolean yes The brand of every event type that names none. An account with brands has one.
primary_color string yes
accent_color string or null yes
sender_name string or null yes The name emails are sent under. Null: the account's name. The address stays ours.
reply_to_email string or null yes Where a visitor's reply goes. Null: the host's own address.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
409 This cannot be done while something else depends on it. The same identifier was already used for a different request. This request is already running. conflict , id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/brands/{brand_id}

One brand.

Operation id
getBrand
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
account.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
brand_id path string yes Limits: pattern ^brd_[0-9a-z]{26}$.

Answers

200 The brand. application/json

Field Type Always sent Notes
id string yes
name string yes
is_default boolean yes The brand of every event type that names none. An account with brands has one.
primary_color string yes
accent_color string or null yes
sender_name string or null yes The name emails are sent under. Null: the account's name. The address stays ours.
reply_to_email string or null yes Where a visitor's reply goes. Null: the host's own address.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
429 Too many attempts. rate_limited

PATCH /v1/brands/{brand_id}

Changes a brand, or makes it the default. Send the version you read. A primary colour the palette rule refuses is refused, with the nearest colour that passes, and nothing is saved.

Operation id
updateBrand
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
account.update
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
brand_id path string yes Limits: pattern ^brd_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
name string no
primary_color string no #rrggbb. Refused when it is under 3:1 against white or the page background, or when neither white nor dark text reaches 4.5:1 on it; the refusal names the nearest colour that passes.
accent_color string or null no
sender_name string or null no
reply_to_email string or null no
is_default boolean no true makes this the default brand, and the old default stops being it in the same change. A brand stops being the default only when another one becomes it. Values: true .

Answers

200 The brand after the change. application/json

Field Type Always sent Notes
id string yes
name string yes
is_default boolean yes The brand of every event type that names none. An account with brands has one.
primary_color string yes
accent_color string or null yes
sender_name string or null yes The name emails are sent under. Null: the account's name. The address stays ours.
reply_to_email string or null yes Where a visitor's reply goes. Null: the host's own address.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/brands/{brand_id}

Deletes a brand that is not the default. Every event type that named it wears the default brand from then on, each with a new version. The default brand is refused: make another brand the default first.

Operation id
deleteBrand
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
account.update
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
brand_id path string yes Limits: pattern ^brd_[0-9a-z]{26}$.
version query integer yes Limits: at least 1.

Answers

204 The brand has been deleted.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
429 Too many attempts. rate_limited