# Email Notification

An **Email Notification** is a configuration rule that binds a system event trigger (like a completed challenge or streak about to break) to a specific [Email Template](/email-template). When the defined event occurs, the platform automatically resolves the associated template, merges recipient data, and sends the transactional email.

---

## How it works

1. **Design a template** — set up an [Email Template](/email-template) containing the subject line, HTML copy, and brand styling.
2. **Create a notification rule** — map a system event trigger (`eventCode`) to your template (`emailTemplateId`).
3. **Activate the rule** — set the status to `live`. The system will now listen for that event.
4. **Trigger email** — when a member triggers the target event (e.g. completes a milestone), the platform runs the notification rule, renders the template, and sends the email to the member's registered email address.
5. **Log delivery** — each dispatch attempt creates a record in the [Email Notification Log](/email-notification-log) for debugging and auditing.

---

## Fields

### Basic information

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `eventCode` | enum | ✅ | — | The system event code that triggers the email. See [Trigger Events](#trigger-events) below. |
| `emailTemplateId` | UUID | ✅ | — | The unique identifier of the [Email Template](/email-template) to use. |
| `status` | enum | ✅ | `draft` | The rule status: `draft` · `live` · `paused`. Only `live` notifications trigger outgoing emails. |

---

## Trigger events

The `eventCode` determines which platform action triggers this notification rule:

| Event Code | Trigger Condition |
|---|---|
| `streak_progress_broken` | Sent when a user fails to maintain their streak and it resets |
| `streak_progress_to_be_broken` | Sent as a warning reminder before a streak period expires |
| `streak_progress_completed` | Sent when the user completes the overall target streak |
| `streak_progress_non_milestone_completed` | Sent when the user completes a non-milestone in a streak |
| `streak_progress_milestone_completed` | Sent when the user completes a milestone in a streak |
| `streak_progress_in_progress` | Sent when the user makes a progress in a streak but does not complete any non-milestone or milestone |
| `challenge_progress_failed` | Sent when a challenge window ends and target is not met |
| `challenge_progress_to_be_failed` | Warning warning before a challenge window closes |
| `challenge_progress_completed` | Sent when the user completes the challenge target |
| `challenge_progress_milestone_completed` | Sent when the user reaches a milestone in a challenge |
| `challenge_progress_in_progress` | Sent when the user makes a progress in a challenge but does not complete any milestone |

---

## Real-world examples

**🛍️ E-commerce — Challenge Completed Notification**

Automates sending a congratulatory email when a challenge is successfully finished:

```json
{
  "eventCode": "challenge_progress_completed",
  "emailTemplateId": "c123e456-e89b-12d3-a456-426614174000",
  "status": "live"
}
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full control over notification rules |
| End user | *(none)* | No access |
| Guest user | *(none)* | No access |

---

## Related resources

| Resource | Description |
|---|---|
| [Email Template](/email-template) | The subject line and body layout linked to this notification trigger |
| [Email Notification Log](/email-notification-log) | Read-only delivery logs recording the execution history of notifications |
| [Member](/member) | The recipient of the outgoing email notification |

---

## API reference

See the [API Reference](/api/email_notification) for full request/response schemas and interactive examples for:

- `GET /schema/email_notification/record` — list email notifications
- `POST /schema/email_notification/record` — create an email notification
- `GET /schema/email_notification/record/{id}` — get an email notification by ID
- `PATCH /schema/email_notification/record/{id}` — update an email notification
- `DELETE /schema/email_notification/record/{id}` — delete an email notification