/v1/workspaces/{workspace_id}/brandAuthReplace 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 · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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 · uriPublic URL of your logo. Recommended: PNG/SVG, ≤200px tall, hosted on a domain you control or any CDN reachable at send time.
brand_namestringDisplay name shown in the email header (falls back to your workspace display name if not set).
primary_colorstringPrimary brand color. Used for buttons, links, and accent strokes. Hex string (e.g. #2d29d7).
secondary_colorstringSecondary brand color, typically darker than primary. Used for hover states + secondary accents.
text_colorstringBody text color (default: near-black).
muted_text_colorstringMuted text color for footers + secondary copy.
background_colorstringPage background — the area outside the email card.
card_background_colorstringEmail card background.
font_stackstringCSS font-family stack. Email clients can't use webfonts reliably — list system fonts in fallback order.
button_radiusstringCSS length value for button border-radius (e.g. "6px", "0", "9999px" for fully round).
container_max_widthstringMaximum width of the email card. Bulletproof tables max-out at this.
footer_htmlstringCustom HTML to render in the email footer. Inline styles only — no <style> tags. Used by templates that opt into `{{> bp.footer}}`.
footer_addressstringPostal address line for compliance footers (CAN-SPAM, etc.). Plain text, displayed verbatim.
social_linksobjectMap 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.
extrasobjectExtra 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*objectFully-resolved tokens every render uses. The frontend reads this for previews so what the editor shows == what recipients get.
raw*objectUser-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": {}
}