GroundmailDocs
Markdown

Brand

Updated Nov 2, 20263 min read

Your brand is your logo, your colors and your footer, set once for the workspace. Templates follow it: every setting a template doesn't set itself (page and content colors, fonts, button style, global CSS) comes from the brand, and new templates show your logo on top and your company name, mailing address and website in the footer. Change the brand and templates that follow it change with it, from their next send.

In the dashboard: Templates › Brand, or Add your brand on Templates for a one-minute setup (logo, color, footer). The setup can read your logo and colors from your website.

Base URL: https://api.groundmail.dev

Auth:

Reading and changing the brand needs the templates:write scope.

HTTP
Authorization: Bearer gm_...

Get the brand

is_set is false until anything is set. Until then every template renders with its own settings.

HTTP
GET /brand
JSON
{
  "brand": {
    "is_set": true,
    "settings": {
      "backgroundColor": "#f1eee8",
      "linkColor": "#2f6feb",
      "theme": { "buttonBackground": "#2f6feb", "buttonTextColor": "#ffffff", "buttonRadius": 6 }
    },
    "logo": { "url": "https://cdn.acme.com/logo.png", "width": 120, "align": "left" },
    "accent_color": "#2f6feb",
    "company_name": "Acme Inc",
    "address": "548 Market St, San Francisco, CA 94104",
    "website": "https://acme.com",
    "updated_at": "2026-11-02T18:00:00.000Z"
  }
}

Update the brand

Field What it is
settings The look: any of a template's design.settings keys (backgroundColor, contentBackgroundColor, textColor, linkColor, fontFamily, contentWidth, darkMode, globalCss, and theme with buttonBackground, buttonTextColor, buttonRadius, bodyFontSize, lineHeight, headingFontSize). Colors are hex. Sending settings replaces the brand's look, so read it first and change what you need.
logo { url, align, width? }. url is an https image; PNG or JPEG shows in every mail app (Gmail and Outlook don't show SVG). align is left or center; width is in px (default 120). null removes it.
accent_color The line across the top of every email. null removes it.
company_name, address The footer's first line: Acme Inc · 548 Market St…. Inbox providers and the law expect a company name and mailing address on product email; a PO box is fine.
website Linked from the logo and in the footer next to Unsubscribe. acme.com is read as https://acme.com.

Fields you leave out keep their value; null clears one. A field that isn't valid (a color that isn't hex, a logo that isn't https) returns 400 with a validation_error.

HTTP
PUT /brand
TypeScript
await groundmail.brand.update({
  logo: { url: 'https://cdn.acme.com/logo.png', align: 'left' },
  accent_color: '#2f6feb',
  settings: {
    linkColor: '#2f6feb',
    theme: { buttonBackground: '#2f6feb', buttonTextColor: '#ffffff' },
  },
  company_name: 'Acme Inc',
  address: '548 Market St, San Francisco, CA 94104',
  website: 'acme.com',
})

Which templates follow the brand

  • New templates made in the dashboard, from a starter (POST /templates/from-starter) or for an automation follow the brand, with the logo header and company footer on. A blocks template created with POST /templates and no design does too.
  • Templates you made before the brand keep looking exactly as they do. A template still on our default look follows the brand's look, without the header and footer; a template with a look of its own keeps every setting it has.
  • HTML templates are your own HTML and never change.

In the template editor, Edit theme shows each setting as From your brand or This template. Change a setting to override it for that template only; Reset puts it back on the brand, and Reset all to brand drops every override. Use brand header and footer turns the logo and company footer on or off for that template.

In a template's design, settings.brand records this: { "overrides": ["linkColor"], "headerFooter": true } means the template sets its own link color, takes everything else from the brand, and shows the header and footer. Send a design without settings.brand and it is treated like a template made before the brand.

CLI and MCP

--color sets buttons, links and the line across the top, and picks white or dark button text so it stays readable. --settings-file brand.json replaces the look. Agents use the get_brand and update_brand MCP tools.

Terminal
groundmail brand get
groundmail brand set --logo-url https://cdn.acme.com/logo.png --color '#2f6feb' --company "Acme Inc" --address "548 Market St, San Francisco, CA 94104" --website acme.com

Was this page helpful?