Create OSM Template API

The Create OSM Template API can be used to create an OSM template in MoEngage. This API helps you upload templates created outside the MoEngage ecosystem to MoEngage and use them for campaign creation.

info	Information API templates cannot be used in the Drag and Drop Editor in the MoEngage Dashboard. They are only supported for the Custom HTML Editor.

API Endpoint

POST https://api-0X.moengage.com/v1.0/custom-templates/osm

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: "Basic Base64_ENCODED_WORKSPACEID_APIKEY=="}

Follow the steps below to obtain the username and password details from the MoEngage Dashboard:

API authentication.png

Navigate to Settings > Account > APIs.
Copy the following details:
- Username: Under Workspace ID (earlier App ID), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Campaign report/Business events/Custom templates/Catalog API tile to copy the API key.
Use the above details to authenticate the API requests.

Request Headers

Key	Required	Sample Values	Description
Content-Type	Required	{"Content-Type": "application/json"}	Set the Content-Type header to application/json.
Authorization	Required	{"Authorization: "Basic Base64_ENCODED_WORKSPACEID_APIKEY=="}	This authentication parameter, used for access control, must be passed in the request. To generate the authentication header, refer to Authentication.

Request Body

Key

Type

Required

Data type

Description

basic_details

JSON

Mandatory

String

Details about the template, including its payload and template type.

payload:
- Payload type should be HTML only. The data type will be a string.
- No limit restriction on field length
- For the payload structure, refer here.
template_type:
- string value, three options possible - BANNER, POP_UP, or NUDGE

meta_info

JSON

Mandatory

String

This field contains information about the template being created, such as its name, version, and ID and the creator's details.

Keys:

template_name (mandatory)
template_id (mandatory)
template_version (mandatory)
created_by (mandatory)

Example:

{
"template_name": "test",
"template_id": "123456"
"template_version": "1",
"created_by": "test@ABC.com"
}

Payload Example

{

  "basic_details": {

    "payload": "<html>\n <head>\n \n <title>Scratch Card</title>\n \n</head>\n<body>\n\n <div class=\"screen-1\">\n <h2>Scratch And Win</h2>\n <h4>Exciting Prized Await You!</h4>\n <div class=\"card-container\">\n <div id=\"card\" class=\"scratchpad\"></div>\n </div>\n </div>\n \n <div class=\"winning-screen\">\n <div class=\"greeting-text\">\n <p>Congratulations, you won <span></span></p>\n </div>\n <div class=\"greeting-img\">\n <div class=\"card-container\" id=\"target\">\n <div class=\"scratchpad\">\n\n </div>\n </div>\n <div>\n <p>Copy this code and use during checkout.</p>\n <button onclick=\"moengage.openRichLanding('https://www.moengage.com'); moengage.trackClick(1); moengage.dismissMessage();\">Continue shopping</button>\n </div>\n </div>\n </div>\n \n <div class=\"loosing-screen\">\n <div class=\"greeting-text\">\n\n <p>Sorry, You didn't win anything</p>\n </div>\n <div class=\"greeting-img\">\n <div class=\"card-container\">\n <div class=\"scratchpad\">\n <p>Better luck next time</p>\n </div>\n </div>\n <button onclick=\"moengage.openRichLanding('https://www.moengage.com'); moengage.trackClick(1); moengage.dismissMessage()\">Continue shopping</button>\n </div>\n </div>\n</body>\n</html>",

    "template_type": "BANNER"

    },

    "meta_info": {

        "template_name": "test"

        "template_id": "123456",

        "template_version": "1",

        "created_by": "test@ABC.com"

      }

}

Response

Status

Key

Data Type

Description

Success

external_template_id

String

This field contains the unique ID corresponding to a successful custom template creation. This template ID is used as header input for update, search, or any kind of template modifications in later stage.

Failure

error

JSON object

This field contains the reason for the request's failure.

Structure:

"error": {

"code": "<error_code>",

"message": "<error_message>" ,

"details": [],

"request_id": "<unique identifier for the request>

}

The error object contains the following fields:

code - This field contains the error code that provides a brief explanation of the error and is a string. For example, 400 - Bad Request, 401- Authentication required, and so on. This field is present in the response only in the case of errors.
message - This field describes why the request has failed and is a String. For example, in the case of a duplicate request (400- Bad Request), the following message will be present: 'Duplicate - template_id and template_version'.
details - This is a List of the error details objects. Each object contains the following information:

{

"code": "<Descriptive Error Code>",

"target": "<Denotes the field causing the issue or a brief description of the error message in some cases >",

"message": "<Descriptive Error Message>"

}

request_id - This field contains the unique ID pertaining to the request.

For example, in the case of a 400 request where the request is trying to create a template that is already present, the following error object is returned.

For the sample response, refer here.

Response Codes

Status Code	Request State	Description
200	Success	Template created successfully.
400	Bad Request	This response is returned when the required parameters are missing from the request, when the provided parameters are invalid, or when a template already exists with the same version, name, or ID.
401	Authorization Failure	This response is returned when the authorization parameters are missing in the HTTP Auth Header.
415	Unsupported File Type	This response is returned when the header Content-Type is not provided/is not supported.
429	Rate Limit Breach	This response is returned when the number of requests per minute has exceeded the rate limit, or the number of templates has exceeded the allowed quota per channel.
5xx	Internal Server Error	This response is returned when the system runs into an unexpected error.

Rate Limit

The rate limit is 100 RPM. You can upload a maximum of 100 templates per minute.

Sample cURL Request

# curl --location 'https://api-0X.moengage.com/v1.0/custom-templates/osm' \

--header 'Content-Type: application/json' \

--header 'Authorization: Basic Q000RDFMXk4ySU1KTkJKOVMMWEFVNzNEOlIxWk9PS0FZUENCNg==' \

--data-raw '{

    "basic_details": {

        "payload": "<html>\n <head>\n \n <title>Scratch Card</title>\n \n</head>\n<body>\n\n <div class=\"screen-1\">\n <h2>Scratch And Win</h2>\n <h4>Exciting Prized Await You!</h4>\n <div class=\"card-container\">\n <div id=\"card\" class=\"scratchpad\"></div>\n </div>\n </div>\n \n <div class=\"winning-screen\">\n <div class=\"greeting-text\">\n <p>Congratulations, you won <span></span></p>\n </div>\n <div class=\"greeting-img\">\n <div class=\"card-container\" id=\"target\">\n <div class=\"scratchpad\">\n\n </div>\n </div>\n <div>\n <p>Copy this code and use during checkout.</p>\n <button onclick=\"moengage.openRichLanding('https://www.moengage.com'); moengage.trackClick(1); moengage.dismissMessage();\">Continue shopping</button>\n </div>\n </div>\n </div>\n \n <div class=\"loosing-screen\">\n <div class=\"greeting-text\">\n\n <p>Sorry, You didn't win anything</p>\n </div>\n <div class=\"greeting-img\">\n <div class=\"card-container\">\n <div class=\"scratchpad\">\n <p>Better luck next time</p>\n </div>\n </div>\n <button onclick=\"moengage.openRichLanding('https://www.moengage.com'); moengage.trackClick(1); moengage.dismissMessage()\">Continue shopping</button>\n </div>\n </div>\n</body>\n</html>",

        "template_type": "BANNER"

      },

    "meta_info": {

      "template_name": "Test",

      "template_id": "123123123",

      "template_version": "1",

      "created_by": "testuser@moengage.com"

      }

}'

Sample Response

Sample Response for a successful request
{
  "external_template_id": "d05a44f0-a7cf-471a-bcb6-63054800a367"
}

Sample response for bad request
{
    "error": {
        "code": "400 Bad Request",
        "message": "Duplicate - template_id and template_version",
        "details": [
            {
                "code": "InvalidValue",
                "target": "Duplicate - template_id and template_version",
                "message": "template_id:13343440 template_version:1 is already present."
            }
        ],
        "request_id": "xZLmJvUi"
    }
}

Sample Response for Authentication/Authorization failure
{
   "title": "Authentication required",
   "description": "MOE-APPKEY missing in Authentication Header"
}

Sample Response for Unsupported Media Type
{
   "title": "Unsupported media type",
   "description": "Content type is not supported"
}

Sample Response for Rate Limit Breach
{
    "response_id": "OUUkHvcn",
    "type": "custom_template",
    "error": {
        "code": "Too Many Requests",
        "message": "API rate limit breached. Current limit: n/m mins"
    }
}
Sample Response for Template Limit Breach
{
   "error": {
       "code": "400 Bad Request",
       "message": "Maximum Template limit exceeded",
       "details": [
           {
               "code": "NotSupported",
               "target": "Maximum Template limit exceeded",
               "message": "You have already created maximum allowed template allowed for client"
           }
       ],
       "request_id": "eLeZXIlW"
   }
}

Sample Response for server side errors
{ 
    "title": "Internal Server Error",
    "message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team"
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.