Mail API reference

Mail API · Brand

put/v1/workspaces/{workspace_id}/brandAuth

Replace the workspace brand. Any field omitted from the body is reset to the platform default for that field. To partially-update, send back what GET returned with the desired diff applied.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

logo_urlstring · uri

Public URL of your logo. Recommended: PNG/SVG, ≤200px tall, hosted on a domain you control or any CDN reachable at send time.

brand_namestring

Display name shown in the email header (falls back to your workspace display name if not set).

primary_colorstring

Primary brand color. Used for buttons, links, and accent strokes. Hex string (e.g. #2d29d7).

secondary_colorstring

Secondary brand color, typically darker than primary. Used for hover states + secondary accents.

text_colorstring

Body text color (default: near-black).

muted_text_colorstring

Muted text color for footers + secondary copy.

background_colorstring

Page background — the area outside the email card.

card_background_colorstring

Email card background.

font_stackstring

CSS font-family stack. Email clients can't use webfonts reliably — list system fonts in fallback order.

button_radiusstring

CSS length value for button border-radius (e.g. "6px", "0", "9999px" for fully round).

container_max_widthstring

Maximum width of the email card. Bulletproof tables max-out at this.

footer_htmlstring

Custom HTML to render in the email footer. Inline styles only — no <style> tags. Used by templates that opt into `{{> bp.footer}}`.

footer_addressstring

Postal address line for compliance footers (CAN-SPAM, etc.). Plain text, displayed verbatim.

social_linksobject

Map of social-platform → URL. Recognized keys: twitter, x, linkedin, github, instagram, facebook, youtube, tiktok, mastodon, bluesky, web. Keys are stored and returned exactly as sent.

extrasobject

Extra key/value tokens addressable as {{brand.extras.<key>}} in templates. Use for marketing strings, secondary accent colors, etc. Keys are stored and returned exactly as sent (`hero_title` stays `hero_title`, `heroTitle` stays `heroTitle`), so `<key>` is the key you sent.

Example: {"hero_title":"Spring sale"}

Response · 200

resolved*object

Fully-resolved tokens every render uses. The frontend reads this for previews so what the editor shows == what recipients get.

raw*object

User-set values only (null when the workspace has never customised). Null fields signal "not customised — falling through to default".

Example

Request

PUT https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/brand
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "logo_url": "string",
  "brand_name": "string",
  "primary_color": "string",
  "secondary_color": "string",
  "text_color": "string",
  "muted_text_color": "string",
  "background_color": "string",
  "card_background_color": "string",
  "font_stack": "string",
  "button_radius": "string",
  "container_max_width": "string",
  "footer_html": "string",
  "footer_address": "string",
  "social_links": {},
  "extras": {
    "hero_title": "Spring sale"
  }
}

Response

{
  "resolved": {},
  "raw": {}
}