> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/alerting-integrations/email-notification-settings.md).

# Email

This guide explains how to configure Teleskope email settings in order to send policy violation alert emails from your organization's domain using SendGrid domain authentication.

## Overview

Teleskope sends policy violation alerts via email through SendGrid. By default, emails are sent from `no-reply@teleskope.ai`. To send emails from your own domain, configure the sender address in Teleskope and add DNS records to your domain so SendGrid can send on your behalf.

## Step-by-Step Setup

{% stepper %}
{% step %}

#### Navigate to Email Settings

Go to **Settings > Notification Settings** in Observatory.
{% endstep %}

{% step %}

#### Configure the Sender Email Address

The sender email is composed of three parts:

```
[User] @ [Subdomain] . [Domain]
```

* **User**: the local part of the email (e.g., `alerts`, `automation`)
* **Subdomain**: optional. Only the return-path record is created under this subdomain.
* **Domain**: the domain the DKIM records are created under

We recommend sending from a dedicated subdomain. Enter the full sending host in **Domain** and leave **Subdomain** blank:

* **User**: `alerts`
* **Subdomain**: blank
* **Domain**: `notifications.yourcompany.com`

The sender address is `alerts@notifications.yourcompany.com`, and every DNS record is created under `notifications.yourcompany.com`. This keeps the records separate from any your domain already uses for other email senders.

If you enter `notifications` in **Subdomain** and `yourcompany.com` in **Domain** instead, the sender address is the same, but the DKIM records (hosts containing `._domainkey`) are created under `yourcompany.com`.

Fill in the fields and click the Save icon.
{% endstep %}

{% step %}

#### Set the User Name

Enter the name that appears in the "From" field of the email (e.g., "Teleskope Alerts", "Security Team"). Click Save.
{% endstep %}

{% step %}

#### Add DNS Records to Your Domain

After saving the domain settings, a table of DNS records appears at the bottom of the page. These records are generated by SendGrid and must be added to your domain's DNS configuration.

The table shows:

| Column | Description                                                     |
| ------ | --------------------------------------------------------------- |
| Status | **Pending** (not yet verified) or **Verified** (DNS propagated) |
| Type   | The DNS record type (CNAME or TXT)                              |
| Host   | The DNS hostname to create                                      |
| Value  | The value to set for that record                                |

The records (typically 3 CNAME records) prove to email providers (Gmail, Outlook, etc.) that SendGrid is authorized to send email on behalf of your domain. They enable DKIM signing and SPF alignment.

**How to add the records:**

1. Log in to your DNS provider (e.g., Cloudflare, Route 53)
2. For each row in the table, create a DNS record with:
   * **Type**: as shown (usually CNAME)
   * **Name/Host**: as shown in the Host column
   * **Value/Target**: as shown in the Value column
   * **TTL**: default (or 3600)
     {% endstep %}

{% step %}

#### Wait for DNS Propagation

DNS changes can take up to 48 hours to propagate, though most complete within minutes to a few hours. Teleskope automatically checks verification status with SendGrid each time you load the settings page.

Once all records show **Verified**, your domain is authenticated and emails will be sent from your configured address.
{% endstep %}

{% step %}

#### Optional: Configure CC Emails

Enter a comma-separated list of email addresses that should be copied on every policy alert email. Click Save.
{% endstep %}

{% step %}

#### Optional: Configure Reply-To

Set a Reply-To name and email address. When recipients reply to an alert email, the reply goes to this address instead of the sender. Click Save.
{% endstep %}

{% step %}

#### Optional: Set a Logo URL

Enter a URL to your organization's logo (PNG or JPG). This logo will appear in the header of policy alert emails. Click Save.
{% endstep %}
{% endstepper %}

## Troubleshooting

{% hint style="warning" %}
**DNS records show "Pending" after 48 hours**\
Verify the records were added correctly in your DNS provider. Check for typos in the Host or Value fields. Some providers require you to omit the base domain from the Host (e.g., enter `em1234` instead of `em1234.yourcompany.com`).
{% endhint %}

{% hint style="warning" %}
**"An A, AAAA, or CNAME record with that host already exists" error**\
Your domain already uses that host name for another email sender. Do not change or delete the existing record; other email sent from your domain depends on it. Instead, enter a dedicated sending subdomain (e.g., `notifications.yourcompany.com`) in **Domain**, leave **Subdomain** blank, and click Save. Then add the new records shown in the table. If the error persists, contact Teleskope support.
{% endhint %}

{% hint style="warning" %}
**Emails not being received**\
Check that the domain is verified (all records show "Verified"). Check the recipient's spam/junk folder. Ensure the sender address is not blocked by the recipient's email provider.
{% endhint %}

{% hint style="warning" %}
**"Failed to load DNS records" error**\
This indicates a connectivity issue with SendGrid. Try refreshing the page. If the issue persists, contact Teleskope support.
{% endhint %}

## Settings Reference

| Setting        | Description                        | Example                         |
| -------------- | ---------------------------------- | ------------------------------- |
| User           | Local part of sender email         | `alerts`                        |
| Subdomain      | Optional return-path subdomain     | blank                           |
| Domain         | Sending domain for DKIM records    | `notifications.yourcompany.com` |
| User Name      | Display name in "From" field       | `Teleskope Alerts`              |
| CC Emails      | Comma-separated CC recipients      | `admin@co.com, security@co.com` |
| Reply To Name  | Name shown when recipient replies  | `Security Team`                 |
| Reply To Email | Address replies are sent to        | `security@yourcompany.com`      |
| Logo URL       | URL to logo image for email header | `https://cdn.co.com/logo.png`   |