> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# Multi-Tenancy Notifications

By default, all tenants use the default email notification style, including logos, colors, and localized text. To customize templates for specific tenants, you can assign each tenant its own branding, style, and localization.

XSP matches reported emails to tenants based on the sender's domain, as defined in [guarded\_tenants.yml](https://docs.xorlab.com/9.0/guarded_tenants_yml.md).

## Define a emailTemplateStyle

In the `shared/email_templates/guarded_tenants.yml` file, you will be able to add the `emailTemplateStyle` optional identifier under the tenants that should use a different style.

For e.g:

```yml theme={null}
---
tenants:
  - uid: 00000000-9d99-4a9b-bdf8-bdfb695b0d67
    authTenantId: xorlab.com
    bccFallbackDomain: xorlab.com
    domains:
      - xorlab.com
      - '**.xorlab.com'
  
  # Tenant with different style
  - uid: 82AB76B4-2B54-4B6F-9F9A-CE79769FFD56
    authTenantId: example.com
    bccFallbackDomain: example.com
    domains:
      - 'example.com'
      - '**.example.com'
      - 'example.dev'
    emailTemplateStyle: exampleDarkModeNoLogo
...
```

After defining the `emailTemplateStyle` attribute in `shared/email_templates/guarded_tenants.yml`, you need to refer to its value (e.g., `exampleDarkModeNoLogo`) in all corresponding configuration files.

Configure the following by replacing the `<emailTemplateStyle>` placeholder with the actual value:

* An optional tenant configuration file that can be customized by modifying `shared/email_templates/info/<emailTemplateStyle>.yml`. If no tenant configuration file is specified, then the `default` tenant configuration is used.
* An optional style file that can be customized by modifying `shared/email_templates/style/<emailTemplateStyle>.yml`. If no style file is specified, then the `default` tenant style is used.
* Define one or more localization files under `shared/email_templates/locale`, naming them as `<emailTemplateStyle>_<language>_<COUNTRY>.yml`, where `<language>` and `<COUNTRY>` follow the IETF BCP 47 standard, as used by [Java Locale](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Locale.html).

  * Specifying the `<COUNTRY>` for a localization file is optional, meaning the localization file could be called `<emailTemplateStyle>_<language>.yml`.
  * A more specific localization file (e.g., `<emailTemplateStyle>_<language>_<COUNTRY>.yml`) takes precedence over the less specific one (e.g., `<emailTemplateStyle>_<language>.yml`)
  * If no template localization file is specified, then the `default` tenant localization file is used.

## Customize text

To customize the content of an existing email notification for a `newtenant` tenant with language `lang` and country `COUNTRY`:

1. Copy the content of `shared/email_templates/locale/default.yml` to the clipboard.
2. Use the context menu for the `locale` folder to create a new file inside of it.
3. Enter `newtenant_lang_COUNTRY.yml` as the name for the file in the dialog box that appears. Click **Create**.
4. Scroll down to the file you just created, click it, and paste the copied content in the right pane.
5. For each template in `newtenant_lang_COUNTRY.yml`, replace the content with a tenant specific localized text.

## Customize style

To customize the look of email notifications for a `newtenant` tenant:

1. Copy the content of `shared/email_templates/style/default.yml` to the clipboard.
2. Use the context menu for the `style` folder to create a new file inside of it.
3. Enter `newtenant.yml` as the name for the file in the dialog box that appears. Click **Create**.
4. Scroll down to the file you just created, click it, and paste the copied content in the right pane.
5. Change the values of `newtenant.yml` according to the tenant style.

## Customize company information

To customize the company information of email notifications for a `newtenant` tenant:

1. Copy the content of `shared/email_templates/info/default.yml` to the clipboard.
2. Use the context menu for the `info` folder to create a new file inside of it.
3. Enter `newtenant.yml` as the name for the file in the dialog box that appears. Click **Create**.
4. Scroll down to the file you just created, click it, and paste the copied content in the right pane.
5. Change the values of `newtenant.yml` according to the tenant company information.

## Set a tenant for an email notification

To select a tenant for an email notification in response to a report:

* Set the `x-ag-tenant` email header in your email system to the desired tenant name for the template (e.g., `newtenant`).

> [!NOTE]
>
> **Custom email header and a tenant**
>
> To read the tenant from a custom header, for example, `my-custom-tenant-header` instead of `x-ag-tenant`, you need to edit `activeguard/core/active_guard.yml` the following way:
>
> ```yaml theme={null}
> emailReporting:
>     ## Header name for tenant identification (default = x-ag-tenant)
>     tenantIdentifyingMailHeaderName: my-custom-tenant-header
> ```
>
> The tenant value must consist of letters (a-z, A-Z), numbers (0-9), underscores (\_), and hyphens (-). Note: periods (.) are not allowed.

## Defining an authentication backend for email notifications

This feature allows configuring a per-tenant authenticationBackend parameter in `guarded_tenants.yml` to ensure that email notifications contain URLs that direct users to the appropriate SSQ portal.

The authenticationBackend parameter should match one of the values defined in the `auth/auth/auth.yml` file under enabledAuthBackends.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.