Skip to main content
POST
/
templates
Create template
curl --request POST \
  --url https://api.onesignal.com/templates \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "app_id": "YOUR_APP_ID",
  "name": "YOUR_TEMPLATE_NAME",
  "isEmail": true,
  "email_subject": "<string>",
  "email_body": "<string>",
  "isSMS": true,
  "dynamic_content": "{\"campaign_id\": {\"A\": {\"title\": \"Custom Title A\", \"message\": \"Custom Message A\", \"url\": \"https://www.onesignal.com\"}, \"B\": {\"title\": \"Custom Title B\", \"message\": \"Custom Message B\", \"url\": \"https://www.onesignal.com/login\"}}}"
}
'
"{\n  \"id\": \"b17ebe45-ae35-4dce-11f8-8c3b3894a432\",\n  \"name\": \"new template created via the API\",\n  \"created_at\": \"2023-08-02T18:09:02Z\",\n  \"updated_at\": \"2023-08-02T18:09:02Z\",\n  \"content\": {\n    \"isAndroid\": true,\n    \"isIos\": true,\n    \"isMacOSX\": true,\n    \"isAdm\": true,\n    \"isAlexa\": null,\n    \"isWP\": true,\n    \"isWP_WNS\": true,\n    \"isChrome\": true,\n    \"isChromeWeb\": true,\n    \"isSafari\": true,\n    \"isFirefox\": true,\n    \"isEdge\": true,\n    \"headings\": {\n      \"en\": \"hello from the api!\"\n    },\n    \"subtitle\": null,\n    \"contents\": {\n      \"en\": \"why hello there!\"\n    },\n    \"global_image\": null,\n    \"url\": \"https://example.com\",\n    \"isEmail\": null,\n    \"email_body\": null,\n    \"email_subject\": null,\n    \"email_preheader\": null,\n    \"isSMS\": null,\n    \"sms_from\": null,\n    \"sms_media_urls\": null,\n    \"email_reply_to_address\": null,\n    \"disable_email_click_tracking\": null\n  }\n}"

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the template_id. Templates streamline and standardize message content across push, email, and SMS channels.
See Templates for more information.

​
How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See Channel Setup for guidance.

​
Push Templates

Requirements:
  • Set the contents property with the English (en) language key.
  • All Push Channel Properties are valid for use in push templates.
  • By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., isAndroid: true disables others).

​
Email Templates

Requirements:
  • Set isEmail: true.
  • Include both email_subject and email_body.
  • All Email Channel Properties are valid for use in email templates.

​
SMS Templates

Requirements:
  • Set isSMS: true.
  • Provide SMS-specific parameters like contents.
  • All SMS Channel Properties are valid for use in SMS templates.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key . See Keys & IDs.

​
Content-Type
string
default:application/json; charset=utf-8
required

Body

application/json
​
app_id
string
default:YOUR_APP_ID
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
name
string
default:YOUR_TEMPLATE_NAME
required

An internal name you set to help organize and track Templates. Maximum 128 characters.

​
contents
object

The main message body with language-specific values. Required for push and SMS templates. Supports Message Personalization.

​
isEmail
boolean

Required to be set true for email templates.

​
email_subject
string

Required for email templates. The subject of the email. Supports Message Personalization.

​
email_body
string

The body of the email in HTML format. Required for email templates. Supports Message Personalization.

​
isSMS
boolean

Required to be set true for SMS templates.

​
dynamic_content
object

Add personalization to your templates programmatically. No need to upload a CSV. See Dynamic Content for details.

Example:

"{\"campaign_id\": {\"A\": {\"title\": \"Custom Title A\", \"message\": \"Custom Message A\", \"url\": \"https://www.onesignal.com\"}, \"B\": {\"title\": \"Custom Title B\", \"message\": \"Custom Message B\", \"url\": \"https://www.onesignal.com/login\"}}}"

Response

The created template record. content reflects the configuration as stored — fields not relevant to the chosen channel are returned as null.

A template record. The content block is a TemplateResourceContent whose populated fields depend on the template's channel(s).

​
id
string<uuid>
required

Template ID in UUID v4 format.

​
name
string

Internal label set when the template was created or last updated. Maximum 128 characters.

​
channel
enum<string>

The primary channel the template is configured for. Note: SMS is uppercased while the others are lowercased.

Available options:
push,
email,
SMS
​
created_at
string<date-time>

ISO-8601 timestamp when the template was created.

​
updated_at
string<date-time>

ISO-8601 timestamp when the template was last updated.

​
content
object

The content block of a template. Every field is nullable: a field is populated only when the corresponding channel feature is enabled for the template. For example, push fields (isAndroid, isIos, headings, ...) are populated for push templates; email fields (isEmail, email_body, ...) for email templates; and SMS fields (isSMS, sms_from, ...) for SMS templates. Cross-channel templates may have multiple feature blocks populated.