Create Template Configuration

Create a new template configuration, supporting settings for template name, type, content, main destination countries, and signature information. After creation, the template status is "Pending Review" and must pass the review before it can be used.

Request URL

POST https://smsapi.engagelab.com/v1/template-configs

Call Authentication

Please refer to Call Authentication to learn how to authenticate API requests.

Request Example

Request Header

POST /v1/template-configs HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

              
              POST /v1/template-configs  HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

This code block in the floating window

Request Body

{ "template_name": "Order Notification Template", "template_type": "utility", "template_content": "Your order {order_no} has been shipped and is expected to be delivered by {delivery_time}", "country_codes": "CN,US", "add_signature": true, "sign_id": "987654321", "sign_position": 2 }

              
              {
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to be delivered by {delivery_time}",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

This code block in the floating window

Request Parameters

Parameter	Type	Option	Description
template_name	String	Required	Template name, up to 255 characters
template_type	String	Required	Template type: `authentication` (authentication / OTP), `utility` (notification), `marketing` (marketing). The legacy value `otp` is mapped to `authentication` for compatibility.
template_content	String	Required	Template content, cannot contain: `【`, `】`, `、`, `测试`, `test`, `[`, `]`
country_codes	String	Required	Main destination country codes, comma-separated
add_signature	Boolean	Optional	Whether to add a signature, default false
sign_id	String	Conditionally Required	Required when add_signature is true, signature ID
sign_position	Integer	Conditionally Required	Required when add_signature is true, signature position: 1-prefix, 2-suffix

Response Parameters

Success Response

The HTTP status code is 200, and the response body contains the following fields:

Field	Type	Description
template_id	String	The created template ID

Success Example

{ "template_id": "123456789" }

              
              {
  "template_id": "123456789"
}

This code block in the floating window

Error Response

The HTTP status code is 4xx/5xx, and the response body contains the following fields:

Field	Type	Description
code	Integer	Error code
message	String	Error details

Error Example

{ "code": 400, "message": "sign status is not approved, can not use" }

              
              {
  "code": 400,
  "message": "sign status is not approved, can not use"
}

This code block in the floating window

Error Codes

Error Code	HTTP Status	Possible Errors
`1000`	`500`	Internal service error; failed to query template list/details; database operation failed when creating, updating or deleting templates; failed to query signature info or pending plans
`2001`	`401`	Authentication failed; `Authorization` missing, malformed, or token invalid
`2002`	`401/403`	Developer token expired or disabled; business has been deleted
`2005`	`400`	IP not on the allowlist: `ip forbidden`
`3001`	`400`	Invalid request JSON format: `not correct parameter format`
`3002`	`400`	Invalid `templateId` format; `template_name` empty or longer than 255 characters; invalid `template_type`; empty `template_content`; empty `country_codes`; missing `sign_id` when `add_signature=true`; invalid `sign_position`; template content contains forbidden characters
`3002`	`400`	Authentication-type template validation failed: must contain `{{code}}` and only supports the two variables `{{code}}` and `{{ttl}}`
`3003`	`400`	Signature is not approved when adding it; template does not belong to the current business; pending-review templates cannot be updated; the template is in use by pending or running plans and cannot be updated or deleted
`4001`	`400`	Template does not exist: `template config not exist`; referenced signature does not exist when creating/updating a template: `sign config not exist`

Common error messages:

sign config not exist: Signature configuration does not exist
sign status is not approved, can not use: Signature status is not approved and cannot be used
template config not exist: Template configuration does not exist
ip forbidden: IP is not on the allowlist
not correct parameter format: Invalid request JSON format

Notes

After creation, the template status is "Pending Review" (status=1) and must pass the review before it can be used to send SMS.
If adding a signature, the signature must be in an approved status.
Template content cannot contain forbidden characters: 【, 】, 、, 测试, test, [, ]
Both template and signature IDs are string-type numbers.

Appendix

Template Configuration Status (status)

Value	Description
1	Pending Review
2	Approved
3	Rejected

Template Type (template_type)

Value	Description
authentication	Authentication / OTP
utility	Notification
marketing	Marketing

The legacy value otp is mapped to authentication for compatibility. Authentication-type template content must contain {{code}} and only supports the two variables {{code}} and {{ttl}}.

Signature Position (sign_position)

Value	Description
0	No signature
1	Prefix
2	Suffix