OneSignal Notifications?c=email API

openapi: 3.2.0
info:
  title: api.onesignal.com Notifications?c=email API
  version: '11.6'
servers:
- url: https://api.onesignal.com
security:
- {}
tags:
- name: Notifications?c=email
paths:
  /notifications?c=email:
    post:
      summary: Email
      description: Send a message using the email channel.
      operationId: email
      x-codeSamples:
      - lang: typescript
        label: Node.js SDK
        source: "import Onesignal from '@onesignal/node-onesignal';\nimport { randomUUID } from 'node:crypto';\n\nconst configuration = Onesignal.createConfiguration({\n    restApiKey: 'YOUR_REST_API_KEY',\n});\nconst apiInstance = new Onesignal.DefaultApi(configuration);\n\nconst notification = new Onesignal.Notification();\nnotification.app_id = 'YOUR_APP_ID';\nnotification.email_subject = 'Welcome to OneSignal';\nnotification.email_body = '<h1>Hello!</h1><p>Thanks for signing up.</p>';\n// Target by External ID: alias keys must match the API (external_id, not externalId).\nnotification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };\nnotification.target_channel = 'email';\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. `randomUUID` is imported from `node:crypto`\n// (available on Node 14.17+) — DO NOT reuse keys across logically distinct sends.\nnotification.idempotency_key = randomUUID();\n\ntry {\n  const response = await apiInstance.createNotification(notification);\n  if (!response.id) {\n    console.warn(\"Notification was not sent:\", response.errors);\n  } else if (response.errors) {\n    console.log(\"Notification created:\", response.id, \"(partial failures:\", response.errors, \")\");\n  } else {\n    console.log(\"Notification created:\", response.id);\n  }\n} catch (e) {\n  if (e instanceof Onesignal.ApiException) {\n    // `e.errorMessages` flattens any error-envelope shape to a `string[]`;\n    // the raw parsed body remains on `e.body`.\n    console.error(\"createNotification failed: HTTP \" + e.code, e.errorMessages);\n  } else {\n    throw e;\n  }\n}"
      - lang: python
        label: Python SDK
        source: "import uuid\nimport onesignal\nfrom onesignal.api import default_api\nfrom onesignal.model.notification import Notification\n\n# See configuration.py for a list of all supported configuration parameters.\n# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.\n# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.\nconfiguration = onesignal.Configuration(\n    rest_api_key = \"YOUR_REST_API_KEY\", # App REST API key required for most endpoints\n    organization_api_key = \"YOUR_ORGANIZATION_API_KEY\" # Organization key is only required for creating new apps and other top-level endpoints\n)\n\n\nwith onesignal.ApiClient(configuration) as api_client:\n    api_instance = default_api.DefaultApi(api_client)\n    notification = Notification(\n        app_id='YOUR_APP_ID',\n        email_subject='Welcome to OneSignal',\n        email_body='<h1>Hello!</h1><p>Thanks for signing up.</p>',\n        include_aliases={'external_id': ['YOUR_USER_EXTERNAL_ID']},\n        target_channel='email',\n        # Idempotency key: a client-generated UUID that lets you safely retry on network\n        # failure. If two requests arrive with the same key inside the 30-day window, only\n        # the first is sent and the second returns the original response. Use uuid.uuid4()\n        # or a similar source of randomness — DO NOT reuse keys across logically distinct\n        # sends.\n        idempotency_key=str(uuid.uuid4()),\n    )\n    try:\n        api_response = api_instance.create_notification(notification)\n        # `api_response.id` discriminates the two HTTP 200 shapes. A falsy value means no\n        # notification was created (e.g. all targets were unreachable / not subscribed).\n        # `api_response.errors` is polymorphic: a `list[str]` in the no-subscribers case, or\n        # a dict keyed by recipient-identifier type (`invalid_player_ids`,\n        # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n        # created but some recipients were skipped. Access via `.get('errors')` rather than\n        # attribute access — the legacy Python generator's `ModelNormal.__getattr__` raises\n        # `ApiAttributeError` for optional fields that the server omitted, so plain\n        # `api_response.errors` would crash on the pure-success path.\n        response_id = api_response.get('id')\n        response_errors = api_response.get('errors')\n        if not response_id:\n            print('Notification was not sent:', response_errors)\n        elif response_errors:\n            print('Notification created:', response_id, '(partial failures:', response_errors, ')')\n        else:\n            print('Notification created:', response_id)\n    except onesignal.ApiException as e:\n        print('Exception when calling DefaultApi->create_notification: %s\\n' % e)\n        print('Status Code: %s' % e.status)\n        # `e.error_messages` flattens any error-envelope shape to a list[str];\n        # the raw body remains on `e.body`.\n        print('Error Messages: %s' % e.error_messages)\n        print('Response Body: %s' % e.body)"
      - lang: php
        label: PHP SDK
        source: "<?php\nrequire_once(__DIR__ . '/vendor/autoload.php');\n\n\n// Configure Bearer authorization: rest_api_key\n$config = onesignal\\client\\Configuration::getDefaultConfiguration()\n                                                ->setRestApiKeyToken('YOUR_REST_API_KEY')\n                                                ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');\n\n\n\n$apiInstance = new onesignal\\client\\Api\\DefaultApi(\n    new GuzzleHttp\\Client(),\n    $config\n);\n\n$notification = new onesignal\\client\\Model\\Notification();\n$notification->setAppId('YOUR_APP_ID');\n$notification->setEmailSubject('Welcome to OneSignal');\n$notification->setEmailBody('<h1>Hello!</h1><p>Thanks for signing up.</p>');\n$notification->setIncludeAliases(['external_id' => ['YOUR_USER_EXTERNAL_ID']]);\n$notification->setTargetChannel('email');\n// Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n// If two requests arrive with the same key inside the 30-day window, only the first is sent\n// and the second returns the original response. Use a strong source of randomness — DO NOT\n// reuse keys across logically distinct sends. We use PHP 7+'s built-in random_bytes() here\n// so the snippet works against this SDK's declared composer.json deps (Guzzle + PSR-7) with\n// no extra install; projects that already pull in ramsey/uuid can swap in\n// `\\Ramsey\\Uuid\\Uuid::uuid4()->toString()` instead.\n$idempotencyKeyBytes = random_bytes(16);\n$idempotencyKeyBytes[6] = chr(ord($idempotencyKeyBytes[6]) & 0x0f | 0x40);\n$idempotencyKeyBytes[8] = chr(ord($idempotencyKeyBytes[8]) & 0x3f | 0x80);\n$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($idempotencyKeyBytes), 4));\n$notification->setIdempotencyKey($idempotencyKey);\n\ntry {\n    $result = $apiInstance->createNotification($notification);\n    // `$result->getId()` discriminates the two HTTP 200 shapes. A falsy value (empty\n    // string or null) means no notification was created (e.g. all targets were\n    // unreachable / not subscribed). `$result->getErrors()` is polymorphic: a `string[]`\n    // in the no-subscribers case, or an object keyed by recipient-identifier type\n    // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n    // the notification WAS created but some recipients were skipped.\n    if (!$result->getId()) {\n        echo 'Notification was not sent: ', print_r($result->getErrors(), true), PHP_EOL;\n    } elseif ($result->getErrors()) {\n        echo 'Notification created: ', $result->getId(), ' (partial failures: ', print_r($result->getErrors(), true), ')', PHP_EOL;\n    } else {\n        echo 'Notification created: ', $result->getId(), PHP_EOL;\n    }\n} catch (\\onesignal\\client\\ApiException $e) {\n    echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n    echo 'Status Code: ', $e->getCode(), PHP_EOL;\n    echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;\n} catch (\\Exception $e) {\n    echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;\n}"
      - lang: go
        label: Go SDK
        source: "package main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"os\"\n\n    \"github.com/google/uuid\"\n    \"github.com/OneSignal/onesignal-go-api/v5\"\n)\n\nfunc main() {\n    configuration := onesignal.NewConfiguration()\n    apiClient := onesignal.NewAPIClient(configuration)\n\n    restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, \"YOUR_REST_API_KEY\")\n\n    notification := onesignal.NewNotification(\"YOUR_APP_ID\")\n    notification.SetEmailSubject(\"Welcome to OneSignal\")\n    notification.SetEmailBody(\"<h1>Hello!</h1><p>Thanks for signing up.</p>\")\n    notification.SetIncludeAliases(map[string][]string{\"external_id\": {\"YOUR_USER_EXTERNAL_ID\"}})\n    notification.SetTargetChannel(\"email\")\n    // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n    // If two requests arrive with the same key inside the 30-day window, only the first is\n    // sent and the second returns the original response. The `github.com/google/uuid` module\n    // is not a declared dep of this SDK; run `go get github.com/google/uuid` (or `go mod tidy`\n    // after importing it) before building. DO NOT reuse keys across logically distinct sends.\n    notification.SetIdempotencyKey(uuid.NewString())\n\n    resp, r, err := apiClient.DefaultApi.CreateNotification(restAuth).Notification(*notification).Execute()\n    if err != nil {\n        fmt.Fprintf(os.Stderr, \"Error when calling `DefaultApi.CreateNotification``: %v\\n\", err)\n        fmt.Fprintf(os.Stderr, \"Full HTTP response: %v\\n\", r)\n        if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {\n            fmt.Fprintf(os.Stderr, \"Response Body: %s\\n\", apiErr.Body())\n        }\n        return\n    }\n    // `resp.GetId()` discriminates the two HTTP 200 shapes. An empty string means no\n    // notification was created (e.g. all targets were unreachable / not subscribed).\n    // `resp.GetErrors()` is `interface{}` because the field is polymorphic: a `[]string` in\n    // the no-subscribers case, or a map keyed by recipient-identifier type\n    // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n    // the notification WAS created but some recipients were skipped.\n    if resp.GetId() == \"\" {\n        fmt.Fprintf(os.Stderr, \"Notification was not sent: %v\\n\", resp.GetErrors())\n    } else if errors := resp.GetErrors(); errors != nil {\n        fmt.Fprintf(os.Stdout, \"Notification created: %s (partial failures: %v)\\n\", resp.GetId(), errors)\n    } else {\n        fmt.Fprintf(os.Stdout, \"Notification created: %s\\n\", resp.GetId())\n    }\n}"
      - lang: ruby
        label: Ruby SDK
        source: "require 'onesignal'\n# setup authorization\nOneSignal.configure do |config|\n  # Configure Bearer authorization: rest_api_key\n  config.rest_api_key = 'YOUR_REST_API_KEY'\n\nend\n\napi_instance = OneSignal::DefaultApi.new\nrequire 'securerandom'\n\nnotification = OneSignal::Notification.new\nnotification.app_id = 'YOUR_APP_ID'\nnotification.email_subject = 'Welcome to OneSignal'\nnotification.email_body = '<h1>Hello!</h1><p>Thanks for signing up.</p>'\nnotification.include_aliases = { 'external_id' => ['YOUR_USER_EXTERNAL_ID'] }\nnotification.target_channel = 'email'\n# Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n# If two requests arrive with the same key inside the 30-day window, only the first is sent\n# and the second returns the original response. Use SecureRandom.uuid — DO NOT reuse keys\n# across logically distinct sends.\nnotification.idempotency_key = SecureRandom.uuid\n\nbegin\n  # Create notification\n  result = api_instance.create_notification(notification)\n  # `result.id` discriminates the two HTTP 200 shapes. An empty string means no\n  # notification was created (e.g. all targets were unreachable / not subscribed).\n  # `result.errors` is polymorphic: an `Array<String>` in the no-subscribers case, or\n  # a Hash keyed by recipient-identifier type (`invalid_player_ids`,\n  # `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS\n  # created but some recipients were skipped.\n  if result.id.to_s.empty?\n    puts \"Notification was not sent: #{result.errors}\"\n  elsif result.errors\n    puts \"Notification created: #{result.id} (partial failures: #{result.errors})\"\n  else\n    puts \"Notification created: #{result.id}\"\n  end\nrescue OneSignal::ApiError => e\n  puts \"Error when calling DefaultApi->create_notification: #{e}\"\n  puts \"Status Code: #{e.code}\"\n  # `e.error_messages` flattens any error-envelope shape to an Array<String>;\n  # the raw body remains on `e.response_body`.\n  puts \"Error Messages: #{e.error_messages}\"\n  puts \"Response Body: #{e.response_body}\"\nend"
      - lang: java
        label: Java SDK
        source: "// Import classes:\nimport java.util.Arrays;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.UUID;\n\nimport com.onesignal.client.ApiClient;\nimport com.onesignal.client.ApiException;\nimport com.onesignal.client.Configuration;\nimport com.onesignal.client.auth.*;\nimport com.onesignal.client.model.*;\nimport com.onesignal.client.api.DefaultApi;\n\npublic class Example {\n  public static void main(String[] args) {\n    ApiClient defaultClient = Configuration.getDefaultApiClient();\n    defaultClient.setBasePath(\"https://api.onesignal.com\");\n\n    HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication(\"rest_api_key\");\n    rest_api_key.setBearerToken(\"YOUR_REST_API_KEY\");\n\n    DefaultApi apiInstance = new DefaultApi(defaultClient);\n    Notification notification = new Notification();\n    notification.setAppId(\"YOUR_APP_ID\");\n    notification.setEmailSubject(\"Welcome to OneSignal\");\n    notification.setEmailBody(\"<h1>Hello!</h1><p>Thanks for signing up.</p>\");\n    Map<String, List<String>> aliases = new HashMap<>();\n    aliases.put(\"external_id\", Arrays.asList(\"YOUR_USER_EXTERNAL_ID\"));\n    notification.setIncludeAliases(aliases);\n    notification.setTargetChannel(Notification.TargetChannelEnum.EMAIL);\n    // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n    // If two requests arrive with the same key inside the 30-day window, only the first is\n    // sent and the second returns the original response. Use UUID.randomUUID() — DO NOT\n    // reuse keys across logically distinct sends.\n    notification.setIdempotencyKey(UUID.randomUUID().toString());\n\n    try {\n      CreateNotificationSuccessResponse result = apiInstance.createNotification(notification);\n      // `result.getId()` discriminates the two HTTP 200 shapes. An empty string means no\n      // notification was created (e.g. all targets were unreachable / not subscribed).\n      // `result.getErrors()` is polymorphic (declared as `Object`): a `List<String>` in the\n      // no-subscribers case, or a Map keyed by recipient-identifier type\n      // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when\n      // the notification WAS created but some recipients were skipped.\n      if (result.getId() == null || result.getId().isEmpty()) {\n        System.out.println(\"Notification was not sent: \" + result.getErrors());\n      } else if (result.getErrors() != null) {\n        System.out.println(\"Notification created: \" + result.getId() + \" (partial failures: \" + result.getErrors() + \")\");\n      } else {\n        System.out.println(\"Notification created: \" + result.getId());\n      }\n    } catch (ApiException e) {\n      System.err.println(\"Exception when calling DefaultApi#createNotification\");\n      System.err.println(\"Status code: \" + e.getCode());\n      System.err.println(\"Reason: \" + e.getResponseBody());\n      System.err.println(\"Response headers: \" + e.getResponseHeaders());\n      e.printStackTrace();\n    }\n  }\n}"
      - lang: csharp
        label: C# SDK
        source: "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics;\nusing OneSignalApi.Api;\nusing OneSignalApi.Client;\nusing OneSignalApi.Model;\n\nnamespace Example\n{\n    public class CreateNotificationExample\n    {\n        public static void Main()\n        {\n            Configuration config = new Configuration();\n            config.BasePath = \"https://api.onesignal.com\";\n            config.AccessToken = \"YOUR_REST_API_KEY\";\n\n            var apiInstance = new DefaultApi(config);\n\n            var notification = new Notification\n            {\n                AppId = \"YOUR_APP_ID\",\n                EmailSubject = \"Welcome to OneSignal\",\n                EmailBody = \"<h1>Hello!</h1><p>Thanks for signing up.</p>\",\n                IncludeAliases = new Dictionary<string, List<string>>\n                {\n                    { \"external_id\", new List<string> { \"YOUR_USER_EXTERNAL_ID\" } }\n                },\n                TargetChannel = Notification.TargetChannelEnum.Email,\n                // Idempotency key: a client-generated UUID that lets you safely retry on\n                // network failure. If two requests arrive with the same key inside the\n                // 30-day window, only the first is sent and the second returns the original\n                // response. Use Guid.NewGuid() — DO NOT reuse keys across logically distinct\n                // sends.\n                IdempotencyKey = Guid.NewGuid().ToString()\n            };\n\n            try\n            {\n                CreateNotificationSuccessResponse result = apiInstance.CreateNotification(notification);\n                // `result.Id` discriminates the two HTTP 200 shapes. An empty string means\n                // no notification was created (e.g. all targets were unreachable / not\n                // subscribed). `result.Errors` is polymorphic: a `List<string>` in the\n                // no-subscribers case, or an object keyed by recipient-identifier type\n                // (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...)\n                // when the notification WAS created but some recipients were skipped.\n                if (string.IsNullOrEmpty(result.Id))\n                {\n                    Debug.WriteLine(\"Notification was not sent: \" + result.Errors);\n                }\n                else if (result.Errors != null)\n                {\n                    Debug.WriteLine(\"Notification created: \" + result.Id + \" (partial failures: \" + result.Errors + \")\");\n                }\n                else\n                {\n                    Debug.WriteLine(\"Notification created: \" + result.Id);\n                }\n            }\n            catch (ApiException e)\n            {\n                Debug.Print(\"Exception when calling DefaultApi.CreateNotification: \" + e.Message);\n                Debug.Print(\"Status Code: \" + e.ErrorCode);\n                Debug.Print(\"Response Body: \" + e.ErrorContent);\n                Debug.Print(e.StackTrace);\n            }\n        }\n    }\n}"
      - lang: rust
        label: Rust SDK
        source: "use onesignal_rust_api::apis::configuration::Configuration;\nuse onesignal_rust_api::apis::default_api;\nuse onesignal_rust_api::models::notification::TargetChannelType;\nuse onesignal_rust_api::models::Notification;\nuse uuid::Uuid;\n\n#[tokio::main]\nasync fn main() {\n    let mut configuration = Configuration::new();\n    configuration.rest_api_key_token = Some(\"YOUR_REST_API_KEY\".to_string());\n\n    let mut notification = Notification::new(\"YOUR_APP_ID\".to_string());\n    notification.email_subject = Some(\"Welcome to OneSignal\".to_string());\n    notification.email_body = Some(\"<h1>Hello!</h1><p>Thanks for signing up.</p>\".to_string());\n    let mut aliases = std::collections::HashMap::new();\n    aliases.insert(\n        \"external_id\".to_string(),\n        vec![\"YOUR_USER_EXTERNAL_ID\".to_string()],\n    );\n    notification.include_aliases = Some(aliases);\n    notification.target_channel = Some(TargetChannelType::Email);\n    // Idempotency key: a client-generated UUID that lets you safely retry on network failure.\n    // If two requests arrive with the same key inside the 30-day window, only the first is\n    // sent and the second returns the original response. The `uuid` crate must be declared\n    // in your own Cargo.toml (Cargo doesn't expose transitive crates by name to downstream\n    // code) — add `uuid = { version = \"1\", features = [\"v4\"] }` to your `[dependencies]`.\n    // DO NOT reuse keys across logically distinct sends.\n    notification.idempotency_key = Some(Uuid::new_v4().to_string());\n\n    match default_api::create_notification(&configuration, notification).await {\n        Ok(resp) => {\n            // `resp.id` discriminates the two HTTP 200 shapes. An empty string or `None`\n            // means no notification was created (e.g. all targets were unreachable / not\n            // subscribed). `resp.errors` is polymorphic (typed as `Option<serde_json::Value>`):\n            // a `Vec<String>` in the no-subscribers case, or an object keyed by\n            // recipient-identifier type (`invalid_player_ids`, `invalid_external_user_ids`,\n            // `invalid_aliases`, ...) when the notification WAS created but some recipients\n            // were skipped.\n            match resp.id.as_deref() {\n                Some(\"\") | None => eprintln!(\"Notification was not sent: {:?}\", resp.errors),\n                Some(id) if resp.errors.is_some() => {\n                    println!(\"Notification created: {} (partial failures: {:?})\", id, resp.errors)\n                }\n                Some(id) => println!(\"Notification created: {}\", id),\n            }\n        }\n        Err(onesignal_rust_api::apis::Error::ResponseError(content)) => {\n            eprintln!(\"create_notification failed: HTTP {}\", content.status);\n            eprintln!(\"Response Body: {}\", content.content);\n        }\n        Err(e) => eprintln!(\"create_notification failed: {:?}\", e),\n    }\n}"
      parameters:
      - name: Authorization
        in: header
        description: Your App API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids).
        required: true
        schema:
          type: string
          default: Key YOUR_APP_API_KEY
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - app_id
              - email_subject
              - email_body
              properties:
                app_id:
                  type: string
                  description: Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).
                  default: YOUR_APP_ID
                include_aliases:
                  type: object
                  description: 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).
                  format: json
                  properties:
                    external_id:
                      description: 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).
                      type: array
                      items:
                        type: string
                target_channel:
                  type: string
                  description: The targeted delivery channel. Required when using `include_aliases`. Accepts `push`, `email`, or `sms`.
                  enum:
                  - push
                  - email
                  - sms
                  default: email
                include_subscription_ids:
                  type: array
                  description: 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).
                  items:
                    type: string
                email_to:
                  type: array
                  description: 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).
                  items:
                    type: string
                included_segments:
                  type: array
                  description: 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).
                  items:
                    type: string
                excluded_segments:
                  type: array
                  description: 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).
                  items:
                    type: string
                filters:
                  type: array
                  description: 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).
                  items:
                    oneOf:
                    - title: Filter
                      description: Required. The fitler object.
                      required:
                      - field
                      - relation
                      type: object
                      properties:
                        field:
                          type: string
                          description: The name of the filter to use.
                          enum:
                          - tag
                          - last_session
                          - first_session
                          - session_count
                          - session_time
                          - language
                          - app_version
                          - location
                          - country
                        relation:
                          type: string
                          description: Used with most filters. See details on the specific filter.
                          enum:
                          - '='
                          - '!='
                          - '>'
                          - <
                          - exists
                          - not_exists
                          - in_array
                          - not_in_array
                          - time_elapsed_gt
                          - time_elapsed_lt
                        key:
                          type: string
                          description: Used with the `tag` filter. This is the tag `key`.
                        value:
                          type: string
                          description: The value of the `field` or tag `key` in which you want to filter with.
                    - title: Operator
                      type: object
                      properties:
                        operator:
                          type: string
                          description: 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.
                          enum:
                          - AND
                          - OR
                          default: AND
                  minItems: 1
                  maxItems: 200
                email_subject:
                  type: string
                  description: The subject of the email. Supports [Message Personalization](/docs/message-personalization).
                  default: This is your email subject.
                email_preheader:
                  type: string
                  description: Preview text displayed after the email subject.
                email_body:
                  type: string
                  description: The body of the email in HTML format. Required if `template_id` is not set. Supports [Message Personalization](/docs/message-personalization).
                name:
                  type: string
                  description: An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.
                template_id:
                  type: string
                  description: The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates).
                custom_data:
                  type: object
                  description: '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:
                  type: string
                  description: 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).
                  default: Your Company
                email_from_address:
                  type: string
                  description: 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:
                  type: string
                  description: 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:
                  type: string
                  description: 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:
                  type: array
                  description: 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 em

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/onesignal/refs/heads/main/openapi/onesignal-notifications-c-email-api-openapi.yml