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",
  "contents": {
    "en": "<string>"
  },
  "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}"

​
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

200

​
id
string
Example:

"b17ebe45-ae35-4dce-11f8-8c3b3894a432"

​
name
string

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

​
created_at
string

The date and time the template was created in ISO 8601 format.

​
updated_at
string

The date and time the template was last updated in ISO 8601 format.

​
content
object