# Email Header

An **Email Header** is a reusable visual block placed at the very top of transactional email notifications sent by Gamopanda (such as streak milestone rewards, challenge completions, or failure notifications). It allows you to maintain consistent branding, logos, and header banners across different email templates.

:::tip
The `htmlContent` field is **localisable**. Pass a `languageCode` query parameter when updating or fetching the email header to manage translations for international customers.
:::

---

## How it works

1. **Create an email header** — define a name, description, status, and write the custom HTML content for your header.
2. **Include brand assets** — embed images (like your brand's logo), styling, and custom background gradients inside the HTML block.
3. **Use template variables** — use curly braces `{{ }}` to insert dynamic values. E.g., `{{$account.name}}` dynamically inserts your account's name.
4. **Link to email templates** — associate the email header with an **Email Template** by setting its `emailHeaderId` field.
5. **Send branded emails** — when Gamopanda dispatches transactional emails using that template, the header is dynamically prepended to the email body.

---

## Fields

### Basic information

| Field | Type | Required | Max length | Description |
|---|---|---|---|---|
| `name` | string | ✅ | 256 | The name of the email header |
| `description` | string | ❌ | 1 024 | A brief description of the email header |
| `status` | enum | ✅ | — | `draft` · `live` · `paused` |

### Content settings

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `htmlContent` | string | ❌ | *(Default template)* | The HTML content of the email header. Supports template variables using curly braces `{{ }}`. This field is localisable. |

:::note
The default `htmlContent` is set to:
```html
<div style="background-color: rgb(124, 58, 237); padding: 30px; text-align: center;">
    <h1 style="color: #ffffff; margin: 0; font-size: 24px; letter-spacing: 1px;">{{$account.name}}</h1>
</div>
```
:::

### Template variables

The `htmlContent` field supports template variables resolved at runtime using curly braces `{{ }}`:

| Variable | Description | Example resolved value |
|---|---|---|
| `{{$account.name}}` | The name of your Gamopanda account | `Acme Shop` |

---

## Real-world examples

**🛍️ E-commerce — Default Brand Header**

Used for standard customer communications.

```json
{
  "name": "Default Brand Header",
  "description": "Used for standard customer communications.",
  "status": "live",
  "htmlContent": "<div style=\"background-color: #7c3aed; padding: 24px; text-align: center;\"><img src=\"https://example.com/assets/logo-white.png\" alt=\"{{$account.name}}\" style=\"height: 40px;\" /></div>"
}
```

---

**🎄 Seasonal — Festive Holiday Header**

Applied to emails sent during seasonal promotion periods.

```json
{
  "name": "Festive Holiday Header",
  "description": "Applied to emails sent during seasonal promotion periods.",
  "status": "live",
  "htmlContent": "<div style=\"background: linear-gradient(to right, #e11d48, #be123c); padding: 32px 20px; text-align: center;\"><h1 style=\"color: #ffffff; margin: 0; font-family: sans-serif; font-size: 28px;\">🎁 Holiday Rewards from {{$account.name}}</h1></div>"
}
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full control over email headers |
| End user | *(none)* | No access |
| Guest user | *(none)* | No access |

---

## Related resources

| Resource | Description |
|---|---|
| [Email Footer](/api#tag/Email-Footer) | Reusable HTML footer appended to transactional emails |
| [Email Template](/api#tag/Email-Template) | Custom templates wrapping the notification message body |
| [Email Notification](/api#tag/Email-Notification) | Subscribed transactional email notification configurations |

---

## API reference

See the [API Reference](/api/email_header) for full request/response schemas and interactive examples for:

- `GET /schema/email_header/record` — list email headers
- `POST /schema/email_header/record` — create an email header
- `GET /schema/email_header/record/{id}` — get an email header by ID
- `PATCH /schema/email_header/record/{id}` — update an email header
- `DELETE /schema/email_header/record/{id}` — delete an email header