Use Templates in Email API
Create, update, delete, and fetch email templates. Use an email template in email APIs.
You can use templates in email APIs to send standard/uniform email messages to customers. By default, the email APIs must be sent only with an approved template.
In order to get a new email template approved, contact your Kaleyra account manager or reach out to the support team, see support. A template is approved based on its relevance to the brand details of the product.
You cannot send an email without a template by default. To enable the email service without a template, contact your Kaleyra account manager or reach out to the support team, see support.
In the email templates, you can specify the values for the parameters, 'from', 'subject', html_body, text_body, and template_name. The parameter values that you provide in the email API call take precedence(override) over the corresponding parameters in the email template.
While using a template in the email API, you must provide the template_id. Make sure to note down the template_id to be able to use in an email API.
Note:
- You can use a textly URL in an email template 'html_body' parameter.
- Both 'static' and 'dynamic' textly URLs are supported.
Create a template
To create a template, use the following endpoint with 'POST' method.
<https://api.kaleyra.io/v1/><SID>/email/templates
The following API body creates an email template.
{
"template_name": "Sample Test_Credit_Card_Renewal_01/05/2022 14",
"subject": "Subject from the template",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder anddiscover it will only take a few minutes to launch your first campaign Quantity:{{quantity}},Maket Value:{{dMarketValue}} Symbol {{symbol}}",
"html_body": "<b>abc</b><h1>Hello User</h1>"
}
Below is the list of parameters used in a email template API request:
| Parameter | Data type | Description | Example | Mandatory |
|---|---|---|---|---|
| template_name | string | Name of the template Note: Only alphanumeric characters, “_”(underscore) and “-”(hyphen) are supported in this field. | “Credit card renewal” | Yes |
| subject | string | Subject of the email | “Sample subject” | No |
| from | string | Sender email | “[email protected]” | No |
| text_body | string | Body of the email in text | “Hello” | No |
| html_body | string | Body of the email in html | "Hello" | No |
Note:
The 'template_name’ is the only mandatory parameter for a template creation.
Make sure to provide values to the other parameters of a template, only when you want to override the corresponding parameter values in the email API request; otherwise, you can skip providing values to the non-mandatory parameters of the template.
The following response is displayed. A template with a template_id is created.
{
"data": [
{
"created_at": "2022-04-12T10:18:51.000Z",
"template_id": "6ffbe894-d0c2-4159-9f54-26ca774f1a06"
}
],
"error": {}
}
Create multiple templates
You can create multiple templates with different template parameter values.
The following template request creates multiple templates at a time.
[
{
"template_name": "Sample Test_Credit_Card_Renewal_1{{currentdate}}",
"subject": "Sample Test_Credit_Card_Renewal",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": ""
},
{
"template_name": "Sample Test_Credit_Card_Renewal_2{{currentdate}}",
"subject": "Sample Test_Credit_Card_Renewal",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": ""
}, {
"template_name": "Sample Test_Credit_Card_Renewal_3{{currentdate}}",
"subject": "Sample Test_Credit_Card_Renewal",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": ""
}, {
"template_name": "Sample Test_Credit_Card_Renewal_4{{currentdate}}",
"subject": "Sample Test_Credit_Card_Renewal",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": ""
}, {
"template_name": "Sample Test_Credit_Card_Renewal_5{{currentdate}}",
"subject": "Sample Test_Credit_Card_Renewal",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": ""
}, {
"template_name": "Sample Test_Credit_Card_Renewal_6{{currentdate}}",
"subject": "Sample Test_Credit_Card_Renewal",
"from": "[email protected]",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": ""
}
]
The following response is displayed.
{
"data": [
{
"created_at": "2022-04-12T10:46:16.000Z",
"template_id": "0527fd03-3d56-4676-8e7c-294512e0159b"
},
{
"created_at": "2022-04-12T10:46:16.000Z",
"template_id": "7cb7c502-cce1-40e4-a6a5-280b71ad8cbc"
},
{
"created_at": "2022-04-12T10:46:16.000Z",
"template_id": "06286ed2-1add-43bd-9d6d-defbca1fecdc"
},
{
"created_at": "2022-04-12T10:46:16.000Z",
"template_id": "e6baaafb-7e21-4fe3-a810-0b6acba2ddb1"
},
{
"created_at": "2022-04-12T10:46:16.000Z",
"template_id": "47b4a60f-4f97-4c06-afec-3d37cee419a1"
},
{
"created_at": "2022-04-12T10:46:16.000Z",
"template_id": "0eeac02f-5292-4cbc-86ee-21ee045d4b39"
}
],
"error": []
}
Fetch a template
You can fetch(search) a template by specifying the template_id with 'GET' method.
Use the endpoint, <https://URL/v1/><SID>/email/templates/<template_id>
For example:
<https://api.kaleyra.io/v1/><SID>/email/templates/6ffbe894-d0c2-4159-9f54-26ca774f1a06
The following details for the template is displayed as response.
{
"data": [
{
"created_at": "2021-12-08T11:10:54.000Z",
"template_id": "6ffbe894-d0c2-4159-9f54-26ca774f1a06",
"template_name": "Sample Test_Credit_Card_Renewal_12021_12_08_16_12_74",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign.",
"html_body": "",
"from": "[email protected]",
"subject": "Sample Test_Credit_Card_Renewal"
}
],
"error": {}
}
To fetch all the templates,
Use the following endpoint with 'GET' method:
<https://api.kaleyra.io/v1/><SID>/email/templates/all
Fetch all the templates with specified pagination
You can fetch multiple templates with pagination by specifying the number of templates to be fetched in each page. To do so, add the parameters, ‘page’ and ‘limit’ to the API call.
- Use the ‘page’ parameter to specify the page number.
- Use the 'limit' parameter to specify the number of templates to be returned in each response.
Note:
Make sure to give a value greater than ‘0’ (zero) for 'page' parameter.
To get a specific number of templates with a specific page number, use the following endpoint with 'GET' method:
https://api.kaleyra.io/v1/email/templates?page={insert_page_no}&limit= {insert_limit_no}
Example 1:
https://api.kaleyra.io/v1//email/templates?page=1&limit=5
This example returns 5 templates in each response as follows:
If there are 14 templates,
Page 1 -> 5
Page 2 -> 5
Page 3 -> 4 (only 4 are remaining to be displayed on page 3).
Example 2:
https://api.kaleyra.io/v1//email/templates?page=1&limit=4
If there are 14 templates,
Page 1 -> 4
Page 2 -> 4
Page 3 -> 4
Page 4 -> 2 (only 2 are remaining to be displayed on page 4).
Update a template
You can update the parameter values of an existing template.
To update an existing template details, use the endpoint with 'PUT' method.
<https://URL/v1/><SID>/email/templates/<template_id>
For example:
https://api.kaleyra.io/v1//email/templates/6ffbe894-d0c2-4159-9f54-26ca774f1a06
Note:
You can update only one template at a time.
The following API script updates the specified template.
{
"template_id": "6ffbe894-d0c2-4159-9f54-26ca774f1a06",
"template_name": "Sample Test_Credit_Card_Renewal_12021_12_08_16_12_74",
"from": "[email protected]",
"text_body": "",
"html_body": "<b>Hey Buddy, this is updated</b>"
}
The following message is displayed and the change is updated in the parameter that you specify.
{
"data": [
{
"template_id": "6ffbe894-d0c2-4159-9f54-26ca774f1a06",
"updated_at": "2021-12-08T11:22:42.802Z"
}
],
"error": {}
Delete a template
You can delete a template that you do not need.
To delete an existing template details, use the endpoint with 'DELETE' method:
<https://URL/v1/><SID>/email/templates/<template_id>
For example:
<https://api.kaleyra.io/v1/><SID>/email/templates/6ffbe894-d0c2-4159-9f54-26ca774f1a06
The following message is displayed and the specified template is deleted.
{
"data": [
{
"template_id": "6ffbe894-d0c2-4159-9f54-26ca774f1a06",
"template_name": "Sample Test_Credit_Card_Renewal_12021_12_08_16_12_74",
"deleted": true
}
],
"error": {}
}
To delete all templates at a single instance, use the following endpoint with 'DELETE' method.
<https://URL/v1/><SID>/email/templates/all
For example:
<https://api.kaleyra.io/v1/><SID>/email/templates/all
{
"data": [
{
"deleted_count": 22,
"message": "delete transaction executed"
}
],
"error": {}
}
Note:
The 'deleted_count' indicates the total number of templates deleted.
Use a template in an email API
You can use a template while sending an email API request. To use a template in the email API request, you must specify the template_id.
To send an email with a template, use the email API endpoint with 'POST' method:
<https://URL/v1/><SID>/email
For example:
<https://api.kaleyra.io/v1/><SID>/email
Subject in email API overrides the subject in the template
-
When the subject in the template is empty, and the email API has a subject, then the email is delivered with the subject passed via the email API.
-
When the template has a subject and the email API does not have a subject, then the email is sent with the subject added from the template.
-
When the template has a subject and the email also has a subject, then the subject in email API takes precedence and the email is delivered with the subject from the email API.
-
When both the template and the email API do not have a subject, the email cannot be delivered as the subject in API is mandatory for the email to be delivered and you must pass a subject in the email API.
{
"from": "[email protected]",
"from_name": "No Reply Email from Kaleyra",
"to": "[email protected]",
"subject": "Subject from the Email API",
"template_id":"6ffbe894-d0c2-4159-9f54-26ca774f1a06",
"text_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign Quantity:{{quantity}},Maket Value:{{dMarketValue}} Symbol {{symbol}}",
"html_body": "",
"reply_to": "[email protected]",
}
The following response is shown, an email is sent to the specified recipient and in the example, the subject in the email API overrides the subject from the template.
{
"data": [
{
"message_id": "38df68cb-3096-43c7-9fb4-372beb06fe96:1",
"to": "[email protected]",
"from": "[email protected]",
"subject": "Subject from the Email API"
}
],
"error": {}
}
Updated about 1 year ago