# Email branding and notices

OhAuthCat emails your customers' IT contacts: setup invitations, certificate expiry, a missing domain record, SCIM token failures and similar notices. What they look like depends on your plan.

| Plan               | What IT contacts receive                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Free and Pro       | OhAuthCat's standard layout, sent from OhAuthCat, with your support address as reply-to when you set one                 |
| Business and above | The same, or sent through your own email provider and sender with [customer IT email](/hosted-portal/customer-it-email/) |

## Branded emails by plan

Emails sent on your behalf to your customers and their users (portal invitations, Doctor setup instructions, and hosted sign-in magic codes, password resets and new-device notices) follow your plan and the `email` branding surface (see [branding](/hosted-portal/branding/#favicon-font-and-per-surface-sets)):

| Plan               | Branded emails                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| Free               | OhAuthCat's standard look; your branding is not used                                             |
| Pro                | OhAuthCat's standard look with your logo row                                                     |
| Business and above | Fully white-labelled: your logo and, when you set one, your own [email color set](#email-colors) |

For the best result in dark mode, also upload a logo made for dark backgrounds and set it as `logo_url_dark` on the `email` surface (Pro and above, validated like `logo_url`). Without one, dark-mode emails show your light logo on a light chip. Password reset links follow your verified custom sign-in domain when you have one.

Emails sent to your own account (usage limits, billing and other account-owner notices) always keep OhAuthCat's look. The IT-contact notices about a connection (certificate expiry, a missing domain record, SCIM token failures and similar) also keep OhAuthCat's brand band.

## Email colors

On Business and above, `surfaces.email.colors` in `PATCH /v1/branding` sets the email palette. It applies to the `email` surface only and never falls back to the main color set; sent on `portal` or `consent` it answers [`parameter_invalid`](/errors/parameter_invalid/). On Free and Pro it answers [`plan_limit_reached`](/errors/plan_limit_reached/) with `param` `surfaces.email.colors`.

Each field is a pair of `light` and `dark` values, as `#rrggbb`. Every value is optional; an unset value uses OhAuthCat's default for that scheme, and an unset `accent` uses the email surface's theme accent.

| Field             | Used for                  | Default light | Default dark |
| ----------------- | ------------------------- | ------------- | ------------ |
| `page_background` | The area around the card  | `#f7f7fd`     | `#0f0f1d`    |
| `card_background` | The message card          | `#ffffff`     | `#15152a`    |
| `text`            | Body text                 | `#15152b`     | `#ededfb`    |
| `muted_text`      | Secondary text and footer | `#4d4d6b`     | `#b1b1d2`    |
| `accent`          | Buttons and links         | `#c94820`     | `#f08a5d`    |
| `border`          | Card and divider borders  | `#e7e6f3`     | `#272748`    |

For example, `{"surfaces": {"email": {"colors": {"text": {"light": "#111827", "dark": "#f3f4f6"}, "accent": {"light": "#1d4ed8", "dark": "#60a5fa"}}}}}` sets the body text and accent and keeps the default backgrounds and border.

The light values render inline; the dark values render for email clients that follow the reader's dark mode, including Outlook's dark mode. With a color set, the email uses only your palette in both schemes.

### Contrast rules

Every color set must meet WCAG AA in both the light and the dark scheme, after unset values are filled with the defaults:

- `text` and `muted_text` need 4.5:1 on `card_background`;
- button text needs 4.5:1 on `accent` (it is picked automatically: white or your darker `text` color, whichever contrasts more);
- `accent` needs 3:1 against `card_background`.

A failing set answers [`parameter_invalid`](/errors/parameter_invalid/). Its `param` names the failing color and scheme, and the message names the pair and the ratio.

For example, a dark `muted_text` that is too faint answers `param` `surfaces.email.colors.muted_text.dark` with the message "Contrast of muted_text on card_background (dark) is 3.10:1; at least 4.5:1 is needed (WCAG AA)".

The check runs again whenever the branding changes, so a later theme change cannot leave a failing set stored.

## Preview an email

The dashboard's email preview renders one email with your plan, your saved email branding (or an unsaved `draft` of `colors`, `logo_url` and `logo_url_dark`) and sample data. Nothing is sent. Pick a template (portal invite, end-user magic code, password reset, new device or Doctor instructions) and a light or dark scheme to see the subject, sender name, HTML and text. Previews are limited to 60 per minute per environment. A draft color set that fails the contrast rules answers `parameter_invalid`, as a save would.

## Reply-to and portal logo

`PATCH /v1/environment` sets `support_email` (used as the reply-to on IT-contact notices and portal invitations, with every email provider) and `portal_logo_url`. Send `""` to clear either one.

## Test a notice

`POST /v1/email_events/test` (scope `environment:write`, or `ohauthcat email test`) sends a sample of a customer-facing notice to an owner or admin of your account, with `[Test]` in the subject. You can send at most 5 test emails per environment per hour.

## Switch notices off

`disabled_notices` in the environment settings turns individual notice kinds off for IT contacts; your own team still receives them.

## Email log

`GET /v1/email_events` lists the emails sent for the environment, newest first, filtered by `kind`, `status` (`sent` or `failed`) and `recipient_domain`. It records the recipient's domain, never the full address.
