> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Email is the Schema for the emails API.

<Note>
  API resource reference for **Email**, part of the [Notification service](/api/notification/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
</Note>

<Warning>
  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
</Warning>

## Identity

|         |                             |
| ------- | --------------------------- |
| Group   | `notification.miloapis.com` |
| Version | `v1alpha1`                  |
| Kind    | `Email`                     |
| Scope   | Project                     |

## Overview

An `Email` represents a concrete message that Datum Cloud should send to a recipient. It references an `EmailTemplate` to render, names the recipient (either a `User` resource or a literal address), and supplies the variables needed to fill in the template. Use it to trigger a one-off notification e-mail within a Project; the platform renders the template, resolves the recipient, and delivers the message, recording the outcome in the resource status.

## Spec fields

| Field                         | Type      | Required | Description                                                                                                           |
| ----------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `spec.templateRef`            | Object    | Yes      | References the `EmailTemplate` that should be rendered.                                                               |
| `spec.templateRef.name`       | string    | Yes      | Name of the referenced `EmailTemplate`.                                                                               |
| `spec.recipient`              | Object    | Yes      | The recipient of the e-mail. Provide exactly one of `userRef` or `emailAddress`.                                      |
| `spec.recipient.userRef`      | Object    | No       | References the `User` resource that will receive the message. Mutually exclusive with `emailAddress`.                 |
| `spec.recipient.userRef.name` | string    | No       | Name of the `User` resource that will receive the e-mail. Required when `userRef` is set.                             |
| `spec.recipient.emailAddress` | string    | No       | Literal e-mail address for the recipient instead of a `User` reference. Mutually exclusive with `userRef`.            |
| `spec.variables`              | \[]Object | No       | Name/value pairs substituted into the template. Each entry requires `name` (as declared in the template) and `value`. |
| `spec.priority`               | string    | No       | Influences the order in which pending e-mails are processed. One of `low`, `normal`, `high`.                          |
| `spec.cc`                     | \[]string | No       | Additional addresses that receive a carbon copy. Maximum 10 addresses.                                                |
| `spec.bcc`                    | \[]string | No       | Addresses that receive a blind-carbon copy. Maximum 10 addresses.                                                     |

## Status fields (read-only)

| Field                 | Type      | Description                                                                                                                     |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `status.conditions`   | \[]Object | Latest observations of the e-mail's state; the standard `Delivered` condition tracks delivery.                                  |
| `status.emailAddress` | string    | The final recipient address used for delivery, after resolving any referenced `User`.                                           |
| `status.subject`      | string    | The subject line used for the e-mail.                                                                                           |
| `status.htmlBody`     | string    | The rendered HTML content of the e-mail.                                                                                        |
| `status.textBody`     | string    | The rendered plain-text content of the e-mail.                                                                                  |
| `status.providerID`   | string    | Identifier returned by the underlying e-mail provider when the message is accepted for delivery, used to track delivery status. |

## Usage

```yaml theme={null}
apiVersion: notification.miloapis.com/v1alpha1
kind: Email
metadata:
  name: welcome-message
spec:
  templateRef:
    name: welcome-template
  recipient:
    emailAddress: person@example.com
  variables:
    - name: firstName
      value: Alex
  priority: normal
```

```bash theme={null}
datumctl apply -f email.yaml --project my-project
datumctl get emails --project my-project
datumctl describe emails welcome-message --project my-project
```

<Tip>
  Run `datumctl explain emails --recursive` to see the full, live field tree for this resource.
</Tip>