---
title: "Email"
method: POST
path: "/notifications?c=email"
---

# Email

`POST /notifications?c=email`

Send a message using the email channel.

## Headers

- `Authorization` string, required

## Request body

- object
  - `app_id` string, required — Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).
  - `include_aliases` object — Target up to 20,000 users by their `external_id`, `onesignal_id`, or your own custom alias. Use with `target_channel` to control the delivery channel. Not compatible with any other targeting parameters like `filters`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#include-aliases).
    - `external_id` string[] — An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).
  - `target_channel` 'push' | 'email' | 'sms' — The targeted delivery channel. Required when using `include_aliases`. Accepts `push`, `email`, or `sms`.
  - `include_subscription_ids` string[] — Target users' specific [subscriptions](/docs/subscriptions) by ID. Include up to 20,000 `subscription_id` per API call. Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).
  - `email_to` string[] — Send email to specific users by their email address. Include up to 20,000 email addresses per API call. If the email address does not exist within the OneSignal App, then a new email Subscription will be created. Can only be used when sending [Email](/reference/email). Not compatible with any other targeting parameters like `filters`, `include_aliases`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message).
  - `included_segments` string[] — Target predefined [Segments](/docs/segmentation). Users that are in multiple segments will only be sent the message once. Can be combined with `excluded_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).
  - `excluded_segments` string[] — Exclude users in predefined [Segments](/docs/segmentation). Overrides membership in any segment specified in the `included_segments`. Not compatible with any other targeting parameters like `filters`, `include_aliases`, or `include_subscription_ids`. See [Sending messages with the OneSignal API](/reference/create-message).
  - `filters` union[] — Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).
    - union
      - object — Required. The fitler object.
        - `field` 'tag' | 'last_session' | 'first_session' | 'session_count' | 'session_time' | 'language' | 'app_version' | 'location' | 'country', required — The name of the filter to use.
        - `relation` '=' | '!=' | '>' | '<' | 'exists' | 'not_exists' | 'in_array' | 'not_in_array' | 'time_elapsed_gt' | 'time_elapsed_lt', required — Used with most filters. See details on the specific filter.
        - `key` string — Used with the `tag` filter. This is the tag `key`.
        - `value` string — The value of the `field` or tag `key` in which you want to filter with.
      - object
        - `operator` 'AND' | 'OR' — Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.
  - `email_subject` string, required — The subject of the email. Supports [Message Personalization](/docs/message-personalization).
  - `email_preheader` string — Preview text displayed after the email subject.
  - `email_body` string, required — The body of the email in HTML format. Required if `template_id` is not set. Supports [Message Personalization](/docs/message-personalization).
  - `name` string — An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.
  - `template_id` string — The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates).
  - `custom_data` object — Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email).
  - `email_from_name` string — The name the email is sent from. Defaults to the 'Sender Name' in the Email Settings of your OneSignal Dashboard. See [Email setup](/docs/email-setup) and [Senders](/docs/senders).
  - `email_from_address` string — The full email address shown in the 'From' field of the email (e.g., `promotions@news.example.com`). This is what recipients see as the sender. If not specified, OneSignal uses the default 'Sender Email' set in your Dashboard's Email Settings. See [Senders](/docs/senders).
  - `email_sender_domain` string — The authenticated sending domain used for email delivery. This domain must be verified in your DNS records and will determine which domain handles the mail transfer. It may not always exactly match the domain in the `email_from_address` (e.g., `email_from_address = news@example.com` while `email_sender_domain = mail.example.com`), but the root domain must align for DMARC compliance. If not specified, OneSignal uses the default sender email's domain configured in your Dashboard. See [Email setup](/docs/email-setup) and [Senders](/docs/senders).
  - `email_reply_to_address` string — The email address users reply to. Defaults to the 'Reply-To' address in the Email Settings of your OneSignal Dashboard. See [Email setup](/docs/email-setup).
  - `email_bcc` string[] — BCC recipients for the email. Maximum 5 addresses. Only supported when the email service provider is OneSignal Email. For every email sent, an additional billable email is sent to each BCC address. See [BCC Emails](/docs/en/email-bcc).
  - `include_unsubscribed` boolean — Used for important account-related, non-marking emails. If set to `true` it will send the email to unsubscribed email addresses. Defaults to `false`. See [Email unsubscribe links & headers](/docs/unsubscribe-links-email-subscriptions).
  - `disable_email_click_tracking` boolean — If set to `true`, the URLs sent within the email will not include link tracking and will be the same as originally set; otherwise, all the URLs in the email will be tracked. See [Email unsubscribe links & headers](/docs/unsubscribe-links-email-subscriptions). Defaults to `false`.
  - `send_after` string — Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`
  - `delayed_option` string — Controls how messages are delivered on a per-user basis: `'timezone'` — Sends at the same local time across time zones. `'last-active'` — Delivers based on each user’s most recent session. Not compatible with [Push Throttling](/docs/throttling). If enabled, set `throttle_rate_per_minute` to `0`.
  - `delivery_time_of_day` string — Use with `delayed_option: 'timezone'` to set a consistent local delivery time. Accepted formats: `'9:00AM'` (12-hour), `'21:45'` (24-hour), `'09:45:30'` (HH:mm:ss).
  - `idempotency_key` string — A unique identifier used to prevent duplicate messages from repeat API calls. See [Idempotent notification requests](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`.

## Response `200`

200

- union — Two variants are possible with HTTP 200, distinguished by the `id` field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect `errors` when `id` is empty.
  - object — Notification was accepted and dispatched to one or more subscribers. `errors` (when present) reports per-channel invalid identifiers; `warnings` (when present) reports non-fatal issues such as unsubscribed external IDs. `external_id` echoes the request's `idempotency_key` (or null when not provided).
    - `id` string, uuid, required — Notification ID in UUID v4 format. If `id` is an empty string, then the message was not sent.
    - `external_id` string, nullable — The `idempotency_key` parameter from the request, echoed back. Null when no idempotency_key was provided. Used to detect duplicate-send attempts — see [Idempotent message requests](/reference/idempotent-notification-requests).
    - `errors` object — Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.
      - `invalid_email_tokens` string[]
      - `invalid_aliases` object — The alias label that was used in the `include_aliases` parameter.
        - `external_id` string[]
        - `onesignal_id` string[]
      - `invalid_player_ids` string[]
    - `warnings` union — Non-fatal warnings emitted alongside a successful send.
      - object — Object form.
        - `invalid_external_user_ids` string — external_ids whose subscriptions are unsubscribed.
      - string[] — Array form. Contains non-fatal warning messages.
  - object — Validation passed but the targeting matched zero subscribers (and the notification is not lightspeed-eligible). HTTP status is 200 even though no message was dispatched. `id` is always the empty string in this branch — use it as the discriminator from the Message Sent variant.
    - `id` '', required — If the message `id` is an empty string, then no message was sent. The request appears to be formatted correctly, but there are issues with the aliases, segments, or filters targeted.
    - `errors` string[], required — Reasons the message was not dispatched. The most common value is `"All included players are not subscribed"`, which means every subscription matched by the segments/aliases/filters was unsubscribed before send time. Per-channel sentinels (e.g., invalid identifiers) may also appear.
    - `warnings` union — Non-fatal warnings emitted alongside a successful send.
      - object — Object form.
        - `invalid_external_user_ids` string — external_ids whose subscriptions are unsubscribed.
      - string[] — Array form. Contains non-fatal warning messages.

## Other responses

- `400` — 400
- `403` — Forbidden. The Authorization key cannot send email for this app, or the request targets a feature the app's plan does not enable.
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)