This API enables you to migrate your templates to Insider One and reduce the time required to recreate them. To complete this migration, get started with the following requirements:
Download the HTML of the email template from your vendor. Make sure that the HTML covers the full content.
Make sure to have an application to execute the operations (e.g., Postman, etc.).
Generate the Email Template API key and save it in the payload for later use. You can generate it in Inone Settings > Integration > Generate API Key > Email Content and Templates.
Migrate templates with the extracted variables via Insider's API.
This API allows you to migrate your promotional emails. Transactional email type is not supported in template migration.
You should migrate your email templates one by one. Each payload in the migrator API should be prepared to migrate only one downloaded template to Insider's email template library.
Extract premigration variables
Before migrating your templates, you must extract the following premigration variables: Template Variables, Dynamic Attributes, and URLs with URL parameters.
Template Variables
Template variables are in the form of {variable.color1} within the template. You need to provide accurate values for each template variable.
Dynamic Attributes
The response that will return for the request will contain two values for each dynamic attribute found:
attributeId: The attribute’s ID on your template. It is found in the format of contact.<id> on the template.
attributeName: The attribute’s corresponding name on your template. This value is the name of the attribute in your vendor. You need to provide Insider with the corresponding value.
If you want to map these before sending your template to Insider One, you need to create custom dynamic attributes in Insider One.
Each attribute ID corresponds to an attribute name on your template. See the complete list of System Fields and Their IDs.
To migrate your template, you must replace the attribute name with the corresponding Insider attribute name. See Insider One's Default Attributes.
To replace these attribute names with Insider attributes, you can use the attribute names in the {{my_attribute_name}} format. If you want to replace a custom attribute, the format should be {{c_subscription_expiry_date}}.
For example, the response for extracting variables returns IDs 1 and 3. These IDs correspond to First Name and E-Mail on your template, respectively. You should replace them with Insider's corresponding attributes when sending the request to migrate your template. In this case, they will be replaced with name and email, respectively, in the request as follows:
"dynamic_attributes": {"1": "name", "3": "email"}URLs with URL parameters
URLs with URL parameters are usually used for analytics and unsubscription links. For further information on the parameters URLs can get, refer to Email Personalization Placeholders.
Insider tracks analytics through its system. That's why these links will be removed. The unsubscription links will be replaced with Insider's unsubscription links.
Endpoint and Headers
POST https://mail.useinsider.com/content/v1/template-migration/vendorname/extract-premigration-variables
Please verify with the Insider One team which vendors are currently supported. Then, replace the {vendorname} in the endpoint with your vendor name in lowercase.
Header | Sample Value | Description |
|---|---|---|
X-INS-AUTH-KEY | 1a2b3c4d5e6f | This Email Template key is required to authorize your request. Refer to API Authentication Tokens to generate your token. |
Content-Type | application/json | This header specifies the media type of the resource. |
Body Parameters
Before sending your request, make sure you create it within the following criteria:
Your template html should be in base64 format.
Your template html should not contain any “view-in-browser” component, display conditions, email recommendations, coupon(s), or any other customized component.
Parameter | Description | Data Type | Required |
|---|---|---|---|
html | Your template HTML in base64 format | String | Yes |
Sample Request
Every request made to the request endpoint requires a request body formatted in JSON
Make sure to replace {vendorname} in the endpoint and auth key sample values in the request before sending it.
Only the base64 format is supported for HTML.
The following is a sample request to extract the premigration variables.
curl --location --request POST 'https://mail.useinsider.com/content/v1/template-migration/vendorname/extract-premigration-variables' \
--header 'x-ins-auth-key: 1a2b3c4d5e6f' \
--header 'Content-Type: application/json' \
--data-raw '{
"html": "VGhpcyBpcyBhbiBleGFtcGxlIGh0bWwgY29udGVudA=="
}'The following is a sample response.
{
"variables": [
"fontfamily",
"footer1color",
"mainbackgroundcolor"
],
"dynamic_attributes": [
{
"attributeId": "1",
"attributeName": "First Name"
},
{
"attributeId": "3",
"attributeName": "E-Mail"
}
],
"urls_with_parameters": [
"https://link.mywebsite.com/mo/$uid$_7655444662333189098.gif",
"https://link.mywebsite.com/u/nrd.php?p=$uid$_1_9aAk3820kAopL30913c5295c3ee3d73180391nkc180912nf18409f7ed8fe5",
"https://link.mywebsite.com/mo/$uid$_76480913468.gif"
]
}Migrate your template with extracted variables
To migrate your templates, you need to send them with the extracted variables and dynamic attributes, if any.
Endpoint and Headers
POST https://mail.useinsider.com/content/v1/template-migration/vendorname/migrate
Please verify with the Insider One team which vendors are currently supported. Then, make sure to replace the {vendorname} in the endpoint with your own vendor name in lowercase.
Header | Sample Value | Description |
|---|---|---|
X-INS-AUTH-KEY | 1a2b3c4d5e6f | This Email Template key is required to authorize your request. Refer to API Authentication Tokens to generate your token. |
Content-Type | application/json | This header specifies the media type of the resource. |
Body Parameters
Before sending your request, make sure you create it within the following criteria:
Your template html should be in base64 format.
Your template html should not contain any “view-in-browser” component, display conditions, email recommendations, coupon(s), or any other customized component.
Your variables should have a value mapping. For example, if you have the fontfamily variable, you should send it along with a font family value in the request.
Your dynamic attribute IDs should have a corresponding Insider attribute name as explained in "Dynamic Attributes" section.
You can keep the URLs with parameters and remove them yourself later, or let Insider remove them. The remove_urls_with_parameters key can get true or false accordingly.
Parameter | Description | Data Type | Required |
|---|---|---|---|
template_name | The name your template will have | String | Yes |
remove_urls_with_parameters | Indicates if your URLs will be removed. | Boolean | Yes |
html | Your template HTML in base64 format | String | Yes |
variables | The extracted variables along with their values | Object | Yes |
dynamic_attributes | The extracted attributes along with their corresponding attribute names at Insider | Object | Yes |
Sample Request
The following is a sample request to migrate your template with variables and dynamic attributes.
Make sure to replace the {vendorname} and auth key sample values in the request before sending your request.
curl --location --request POST 'https://mail.useinsider.com/content/v1/template-migration/vendorname/migrate' \
--header 'x-ins-auth-key: 1a2b3c4d5e6f' \
--header 'Content-Type: application/json' \
--data-raw '{
"template_name": "My migrated template",
"remove_urls_with_parameters": true,
"html": "VGhpcyBpcyBhbiBleGFtcGxlIGh0bWwgY29udGVudA==",
"variables": {"footer1color": "#ffffff", "mainbackgroundcolor": "#ffffff", "fontfamily": "Arial"},
"dynamic_attributes": {"1": "name", "3": "email"}
}'The request above migrates a template with the "My migrated template”. It removes the URLs with parameters from the template. The footer1color, mainbackgroundcolor, and fontfamily variables have their own value mappings. Lastly, the attribute IDs 1 (First Name in your template) and 3 (E-Mail in your template) have Insider's corresponding attribute names as name and email.
If your request is successful, your migrated template will appear under Email Design > Choose Template > Custom Templates. You can select your template and use the Drag & Drop Editor to edit it.
Limitations
All functions must be executed with a simple HTTPS POST request.
The API Key should be provided as the authorization key in the request header. If the key is incorrect, the operation will not be executed.
The rate limit is 60 requests per minute.
Templates with the "view-in-browser" component at the top are not supported for migration.
Templates with display conditions are not supported for migration.
Templates with email recommendation and coupon functionalities are not supported for migration.