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

# Email

> How email intake, composing replies, subscribers, CC handling, and guest access work in Serval

Each team in Serval can have its own email intake address (e.g., `support@yourcompany.com`). When someone sends an email to that address, Serval creates a ticket, threads replies into the right conversation, and can automatically respond — depending on your team's settings and whether the sender is trusted.

This guide covers how email intake works, when Serval responds, how to compose email replies, how subscribers and CC recipients are managed, and how external users are handled.

***

## How email intake works

When someone sends an email to your team's intake address, Serval processes it as follows:

1. **The email is received** and scanned for viruses.
2. **Serval checks whether this is a new request or a reply** to an existing ticket. It uses standard email threading headers (`References`, `In-Reply-To`) to match replies to the correct ticket.
3. **If it's a new email**, a ticket is created and the sender becomes the ticket requester.
4. **If it's a reply**, the message is added to the existing ticket conversation.
5. **An auto-response** is sent to the sender confirming the ticket was created (if enabled).

Serval intelligently threads email replies — including replies from CC'd users — back to the correct ticket. No duplicate tickets are created from replies.

On messages linked to email (inbound or outbound), Serval shows inline **To** and **Cc** routing in the thread. Matched org users and your intake address are labeled; other addresses show as email. Long lists can expand and collapse.

***

## When Serval responds

How Serval responds to an inbound email depends on two things: whether the sender is **trusted** and whether the email is a **new request** or a **reply** to an existing ticket.

### Sender trust

A sender is considered **trusted** when both of these are true:

1. Their email domain is in your team's domain allowlist.
2. The email passes [DKIM verification](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) (proving it actually came from that domain).

If either condition fails — or if the sender's domain is not allowlisted but your team has **Allow all domains** enabled — the sender is treated as **untrusted**.

### Response behavior by scenario

| Scenario                         |  AI responds? | Auto-response sent? | What happens                                                                                                                                                        |
| -------------------------------- | :-----------: | :-----------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trusted sender, new ticket**   | If applicable |   Yes (if enabled)  | Serval creates a ticket with AI active. The AI may respond if it has a helpful answer. A confirmation email is also sent if auto-response is enabled.               |
| **Trusted sender, reply**        | If applicable |          No         | The reply is added to the existing ticket. The AI processes the new message and may respond.                                                                        |
| **Untrusted sender, new ticket** |       No      |   Yes (if enabled)  | Serval creates a ticket but immediately escalates it to a human agent. The AI does **not** respond. A confirmation email is still sent if auto-response is enabled. |
| **Untrusted sender, reply**      |       No      |          No         | The reply is added to the existing ticket and synced to connected channels (e.g., Slack), but the AI does **not** respond. A team member needs to reply manually.   |

### What "AI active" means

Each ticket has an **AI active** flag that controls whether Serval's AI agent processes new messages and generates responses.

* **Trusted sender tickets** start with AI active.
* **Untrusted sender tickets** start with AI inactive and escalated to a human.
* When a team member **escalates** a ticket, AI is deactivated.
* A team member can re-enable AI on any escalated ticket by mentioning **@Serval** in the conversation, or by manually toggling it.

When AI is inactive, Serval still delivers messages to connected channels and notifies subscribers — it just does not generate an AI response.

***

## Email settings

Each team's email channel has its own configuration. Navigate to **Team Settings** > **Channels** > **Email** to manage these settings.

### Trust and domain settings

These settings control who can send emails to your team and how Serval treats those senders.

| Setting               | What it does                                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Domain Allowlist**  | Restricts which sender domains can create tickets. When "Allow all domains" is off, only emails from allowlisted domains are accepted. |
| **Allow all domains** | Accepts emails from any sender, regardless of domain. Senders from non-allowlisted domains are treated as untrusted.                   |

<Warning>
  **If you enable "Allow all domains"**, senders from non-allowlisted domains will **not** get AI responses. Their tickets go straight to your team's queue for a human to handle. Only senders from allowlisted domains with valid DKIM get AI responses. If your team relies on Serval to respond to email requests, make sure the sender's domain is on your allowlist.
</Warning>

### Reply and auto-response settings

These settings control how Serval sends emails back to requesters.

| Setting                  | What it does                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| **Auto-response**        | Sends a confirmation email to the sender when a new ticket is created. Can be toggled on or off. |
| **Custom auto-response** | Replaces the default confirmation message with your own text.                                    |
| **Sender name**          | Customizes the display name on outbound emails.                                                  |

### Subscriber settings

These settings control how subscribers are managed based on email CC headers.

| Setting                                 | What it does                                                                                                                                                                                                |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto-subscribe email recipients**     | On inbound email, adds To and Cc recipients as subscribers (provisioning guests for untrusted domains when needed). On outbound replies, CCs all ticket subscribers except the To recipient and the sender. |
| **Auto-unsubscribe removed recipients** | On inbound replies, removes subscribers whose address is no longer in the latest To or Cc headers.                                                                                                          |

***

## Subscribers

A **subscriber** is anyone who receives notifications about activity on a ticket. There are several ways someone becomes a subscriber:

* **Requester** — The person who created the ticket via email is automatically subscribed.
* **Assignee** — The team member assigned to the ticket is automatically subscribed. Assignees **cannot** unsubscribe.
* **Email To/Cc** — When **Auto-subscribe email recipients** is enabled, anyone in the To or Cc headers of an inbound email is automatically subscribed.
* **Reply Cc** — When an agent sends a public reply on an email ticket, people added to the composer Cc line are subscribed; people removed from the prefilled Cc line are unsubscribed.
* **Manual** — Use the ticket's **Change subscribers** control to add existing org members. If you have permission to create users, you can also type an external email to invite them as a guest subscriber.

### Subscriber notifications

Adding someone as a subscriber does not notify them or tag them. They are not alerted about being added, and they do not see past messages unless they open the ticket. They will only start receiving notifications on **future** activity on the ticket.

### Removing subscribers

Any subscriber can be removed from a ticket, which stops all future notifications for that ticket. This removes **all** subscription reasons at once (requester, commenter, mentioned, etc.).

The one exception: **assignees cannot be unsubscribed**. If someone is both the assignee and a subscriber for other reasons, removing them as a subscriber has no effect while they remain assigned.

A removed subscriber can always be re-added later.

***

## CC handling

### Composing replies

On email tickets, public replies show **To** and **Cc** above the message body (hidden for internal notes). **To** is the ticket requester (or the last inbound sender if the requester has no email). **Cc** is prefilled from subscribers except the requester and you. Editing **Cc** adds or removes subscribers relative to that prefilled list when you send; editing **To** changes the requester.

Outbound email goes to **To**. With **Auto-subscribe email recipients** enabled, all other subscribers are CC'd (except you and the To recipient). The composer Cc field controls who is subscribed; it does not override which subscribers receive the email.

### Auto-subscribe email recipients

This setting changes behavior in both directions:

**Outbound emails (Serval to external):**

* All ticket subscribers are CC'd, except the To recipient and the reply sender.
* Deactivated users are excluded. Addresses that do not resolve to an org user are skipped.

**Inbound emails (external to Serval):**

* Anyone in the To or Cc headers of an incoming email is automatically added as a subscriber.
* Recipients from untrusted domains are provisioned as guests before subscribing (see [External users and guests](#external-users-and-guests) below).

When **Auto-unsubscribe removed recipients** is enabled, subscribers not in the latest inbound To or Cc are removed on reply.

### BCC handling

BCC recipients on inbound emails are **not** added as subscribers and are not visible to Serval. This is standard email behavior — BCC headers are stripped by the sending mail server before delivery.

***

## External users and guests

When an email arrives from someone outside your organization, Serval handles them based on your domain allowlist:

### Trusted domains (allowlisted)

If the sender's domain is in your allowlist and passes DKIM verification, they are created as a regular **organization member**. They have the same access as any other user in your org.

### Untrusted domains

If the sender's domain is **not** allowlisted (and "Allow all domains" is on), they are created as an **organization guest**. Guests have limited access:

* They can only see and interact with tickets they are associated with.
* They cannot browse other tickets, teams, or internal data.
* Their access is scoped to the specific conversations they are part of.

This also applies to Cc'd recipients. If **Auto-subscribe email recipients** is enabled and an inbound email Cc's someone from an untrusted domain, that person is created as a guest and subscribed to the ticket.

### Mailing lists and forwarded email

When emails arrive through mailing lists (e.g., Google Groups) that rewrite the From header, Serval looks for `X-Original-From` and `X-Original-Sender` headers to identify the actual sender. This ensures the ticket is attributed to the right person, not the mailing list address.

***

## Custom From Address (White-Labeled Email)

By default, outbound emails from Serval show a sender address like `your-team@intake.serval.com`. You can configure Serval to send emails that appear to come from your own branded address — for example, `it@yourcompany.com` — so that end users see a familiar sender and your organization's domain.

This requires two things: DNS changes on your domain and a one-time configuration by Serval.

### How it works

Serval sends email through AWS SES. Every email has two "from" addresses:

* The **visible From** — what your recipients see (e.g., `it@yourcompany.com`). This is what you're customizing.
* A **hidden envelope sender** — used by mail servers for SPF checks and bounce routing. Without custom DNS records, this defaults to an Amazon SES address, which means your mail authenticates against Amazon's domain rather than yours. Under a strict DMARC policy, this can cause messages to be quarantined if a forwarder breaks the DKIM signature in transit.

The DNS records below fix this by aligning your domain's SPF authentication with the visible sender, so mail authenticates via both SPF and DKIM independently.

### DNS records to add

Serval will provide you with the exact record values. You need to add two sets of records.

**DKIM records — add to your apex domain (e.g., `yourcompany.com`)**

| Type  | Name                                  | Value                         |
| ----- | ------------------------------------- | ----------------------------- |
| CNAME | `<token1>._domainkey.yourcompany.com` | `<token1>.dkim.amazonses.com` |
| CNAME | `<token2>._domainkey.yourcompany.com` | `<token2>.dkim.amazonses.com` |
| CNAME | `<token3>._domainkey.yourcompany.com` | `<token3>.dkim.amazonses.com` |

<Warning>
  **DKIM records belong on the apex domain, not on a subdomain.** A common mistake is adding them under a subdomain like `serval.yourcompany.com`. If they end up at `<token>._domainkey.serval.yourcompany.com` instead of `<token>._domainkey.yourcompany.com`, DKIM verification will fail. Double-check the hostname field in your registrar before saving.
</Warning>

**Custom MAIL FROM records — add to a dedicated subdomain (e.g., `serval.yourcompany.com`)**

You can choose any unused subdomain. Using something identifiable (like `serval.yourcompany.com` or `mail.yourcompany.com`) makes it clear what it's for. This subdomain is only used for internal mail routing — end users never see it.

| Type | Name                     | Value                                                 |
| ---- | ------------------------ | ----------------------------------------------------- |
| TXT  | `serval.yourcompany.com` | `v=spf1 include:amazonses.com ~all`                   |
| MX   | `serval.yourcompany.com` | `feedback-smtp.us-east-1.amazonses.com` (priority 10) |

If you already have a DMARC record on your domain, no DMARC changes are needed.

### Inbound email forwarding

The DNS records above only affect outbound email. For inbound email — so that replies from end users reach Serval — you need to configure forwarding in your mail provider (e.g., Google Workspace):

* Forward `it@yourcompany.com` → your team's Serval intake address (e.g., `your-team@intake.serval.com`)

Your organization's existing MX record (pointing to Google Workspace or Exchange) handles delivery of inbound mail to your domain. The Serval intake address receives it via the forwarding rule you configure there.

### Enabling custom From in Serval

After your DNS records are in place, contact Serval to complete the setup. Serval will:

1. Verify your domain identity in AWS SES (this can take up to an hour after DNS propagation).
2. Update your instance configuration to send outbound mail from your branded address.
3. Confirm by sending a test email.

We recommend testing in a sandbox team before enabling on your production team.

***

## Best practices

<AccordionGroup>
  <Accordion title="Keep auto-subscribe disabled unless you need it">
    With **Auto-subscribe email recipients** off, outbound replies go only to the To address. Enable it only when your workflow needs other subscribers CC'd automatically. You can still adjust the audience per reply with the composer Cc line.
  </Accordion>

  <Accordion title="Use domain allowlisting to control who can create tickets">
    Rather than allowing all domains, maintain an explicit allowlist of trusted domains. This prevents spam and ensures only legitimate senders can create tickets. Add partner or vendor domains as needed.
  </Accordion>

  <Accordion title="Review subscribers before sending sensitive replies">
    Before replying with sensitive information, check the composer Cc line and the subscriber list. With **Auto-subscribe email recipients** enabled, every subscriber is CC'd on the email—not only the addresses shown in Cc. Remove anyone who should not receive it before sending.
  </Accordion>

  <Accordion title="Understand the guest boundary">
    External users from untrusted domains become guests with limited access. However, they can still see messages on tickets they are subscribed to. If a ticket contains internal-only information, remove external guests from the subscriber list before discussing it, or use internal notes instead of email replies.
  </Accordion>

  <Accordion title="Set up a custom From address for brand consistency">
    Configure Serval to send from your organization's email address (e.g., `it@yourcompany.com`) so recipients see a familiar sender. See [Custom From Address](#custom-from-address-white-labeled-email) above for the setup steps.
  </Accordion>
</AccordionGroup>