---
title: "Create Email Notification"
method: POST
path: "/api/v1/admin/email-notifications"
tags: ["Admin APIs", "email-notifications"]
---

# Create Email Notification

`POST /api/v1/admin/email-notifications`

## Request body

- EmailNotificationCreate — Payload for ``POST /email-notifications`` (saves a draft).
  - `subject` string, required
  - `preview_text` string, nullable
  - `body` string, required
  - `audience` AudienceFilter, required — Audience filter as sent by the UI and stored (denormalised) on the ``email_notifications`` row. Validator guarantees the selector fields match ``mode`` so the resolver doesn't have to second-guess the input.
    - `mode` 'all' | 'plan-tier' | 'clients' | 'dataset-access' | 'users', required
    - `plan_tiers` string[], nullable
    - `client_ids` string[], nullable
    - `asset_ids` string[], nullable
    - `user_ids` string[], nullable
  - `scheduled_for` string, date-time, nullable

## Response `200`

Successful Response

- EmailNotificationResponse — Wire-format for a notification record. Mirrors the TS ``EmailNotification`` interface. ``from_name`` / ``from_address`` are returned on every response so the detail page can show recipients what sender was used — but they're always the configured operational sender.
  - `id` string, uuid, required
  - `subject` string, required
  - `preview_text` string, nullable, required
  - `body` string, required
  - `from_name` string, required
  - `from_address` string, required
  - `status` 'draft' | 'sending' | 'sent' | 'failed', required
  - `audience` AudienceFilter, required — Audience filter as sent by the UI and stored (denormalised) on the ``email_notifications`` row. Validator guarantees the selector fields match ``mode`` so the resolver doesn't have to second-guess the input.
    - `mode` 'all' | 'plan-tier' | 'clients' | 'dataset-access' | 'users', required
    - `plan_tiers` string[], nullable
    - `client_ids` string[], nullable
    - `asset_ids` string[], nullable
    - `user_ids` string[], nullable
  - `recipient_count` integer, nullable, required
  - `sent_count` integer, nullable, required
  - `failed_count` integer, nullable, required
  - `scheduled_for` string, date-time, nullable, required
  - `sent_at` string, date-time, nullable, required
  - `created_by` string, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/a8ca30023371/schema)