# Brand

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:

```http
Authorization: Bearer gm_...
```

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

---

## Get the brand

```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"
  }
}
```

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

## Update the brand

```http
PUT /brand
```

```ts
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',
})
```

| 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`.

## 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

```bash
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
```

`--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.