Any user who designs similar emails sends them every day. The structure of the letter is often the same in each mailing list. Only offers change (promotional codes, banners, product cards, etc.).
Such numerous of newsletters are created automatically, fast and it greatly simplifies the task of a designers or marketers with Stripo API generation.
The Stripo API makes it possible to automatically create email messages with pre-configured and stored modules in the library that define the design and layout of the final email message and an external data source (the source for the content).
The process takes some steps, let's learn on how it works:
1) To begin with, we authenticate and access Stripo API.
Every API call needs to be authenticated. Authentication works by checking a project's access token, which can be generated within a Stripo account by its owner on the Project settings page.
JWT — is a unique key for each project in our system. Remember to keep it safe. It limits the ability to influence the email messages and templates of projects outside the organization for which an access token has been generated.
To generate a JWT token, please go to your "Projects&Groups" settings → "REST API" tab and generate the API key.
REST API Info:
The Stripo API is a standard REST API that supports basic CRUD operations and may be used by the 3rd party applications to automate the email template creation and planning of their further exports and mailings.
Every POST request MUST HAVE Content-Type header.
Currently, we accept only 'application/json' content-type.
The data request is passed to the API by POSTing JSON objects to the API endpoints with the appropriate parameters. The documentation for each API call will contain more details on the parameters accepted by the call.
API Endpoint
All API URLs listed in this documentation are relative to https://stripo.email/emailgeneration/v1/.
For example, the /email call is reachable at https://stripo.email/emailgeneration/v1/email.
The client chooses any service convenient for him/her to use, for example, Postman
Authentication
Once you obtain your JWT token, you will have to use it in every API call you make. The token value must always be specified in a header in every query, as shown in the example below:
Stripo-Api-Auth: YOUR_JWT_TOKEN
How to validate the token?
Please create the needed method by clicking on "+" button.
Then set the GET method and add /validate to the API URL
( https://stripo.email/emailgeneration/v1/validate )
Please set two keys and their value:
Key | Value |
Stripo-Api-Auth | YOUR_JWT_TOKEN |
Content-Type | application/json |
Now you can send the GET call by clicking on the blue button "SEND", and if you have the answer "valid": true in the Body, your token is valid. Status 200 ok.
Once you obtain your token, you must use it in every API call you make according to API Reference docs.
More about available methods here.
2) We start by preparing a template and will generate an email on its base.
We have a header and footer that do not change, they are static. Then it's necessary to define the dynamic part of the template where the data in the email will be written. And we get an email at the output. Done, it's simple!
To check the full STRIPO API documentation, please click here.
At first, in order to start generating an email using the Stripo API, we will distribute the preparation in stages.
Stage 1: Create an auto-generation area within the desired template for the email generation.
This step is needed to get your template ready for API content insertion. It's assumed that you already have a template design that needs to be automatically generated. Typically, the template will contain a few static elements, such as a header and footer, that remain the same in every email generated. Additionally, dynamic elements like product cards or blog articles can be included, with content that varies from one email to another.
In this instance, the header and footer will remain static and won't be modified for future email messages.
To achieve this, all design elements are removed from the template, leaving only those that will remain static.
The result looks like this:
How to set up the generation area?
Now we must set up the generation area — the stripe with added the special class to its code. It’s needed to determine the place where the content should be inserted automatically when the “Generate an email” method is called.
To achieve this, add a blank stripe with a single column in the code editor and include the esd-email-gen-area="name_of_area" class in the td tag of the stripe.
Here, name_of_area is a specific identifier you can choose to label this area as your preference. It can be any name you like.
Below illustrates a stripe with an email generation area labeled as the products-area.
<td class="esd-stripe" align="center" esd-email-gen-area="products-area">
Done!
Stage 2: We save our elements: banners and product cards into modules.
✍️ Please note: all email messages created with the API are built from modules, preparing and saving them carefully is essential.
Save these modules to your "My Modules" tab for easy access. Once saved, they will be displayed as shown in the image below.
It's worth mentioning that modules can be either static (regular) or dynamic (with smart elements inside).
The static module I saved:
And set it's unique ID: structure_with_hero_section
The dynamic module preparation:
Let's prepare product card as well.
The product cards need to have Smart properties to be able to automatically replace data in it. To create a product card with smart properties, please click on the module and select the Data tab.
👍 Good to know
How to set smart properties?
The article https://support.stripo.email/en/articles/5462454-what-are-the-smart-element-and-how-to-use-them will help you to do it.
With this approach, you only have to set up the module once, arranging the variables like title, picture, and price in the desired order and appearance.
Firstly, you should add the needed variables. In my example, there are:
an image of the product;
a price.
the short description;
link to the item on your website;
***According to this logic you can add different variables, e.g. for a title etc.
A configuration tab will be created for each added variable; in this case, there will be 4 tabs.
The rules for applying the values of the variables in our smart element have been set up above. Now, the container with smart properties can be saved as a module by setting its ID (e.g., "product_card" as in our example), and the variables will be retained for future use.
Save only one smart container as a module and set it's ID (e.g.): product_card
Preparing and saving the element (structure) with exact amount of containers.
You should perform the same actions with the other modules as well.
Our template has a structure with three cards in a row, so we will drop the same structure with 3 empty containers to save it.
Saving...
In your case, it can be a structure with any number of containers (up to 8), depending on the template’s design.
Save other needed structures and modules and set their ID.
Stage 3: Starting to generate emails using Postman
According to Stage 2 please create another New Collection by clicking on "+" icon
Then set the POST method and add /email to the API URL
( https://stripo.email/emailgeneration/v1/email )
Please set the same two keys in the Headers tab:
Key | Value |
Stripo-Api-Auth | YOUR_JWT_TOKEN |
Content-Type | application/json |
Then switch with the tab Body, choose raw type and you are ready to create your canonical JSON.
Description of the structure of needed parameters for the JSON
For more details about logic description, please follow here - Basic Logic Explanation
Let's closely examine the following email message we will create using the API.
Within the highlighted green rectangle, we can observe the following modules arranged from top to bottom:
A Hero module with a banner, title text below;
Title module showcasing the text "How To Join With Us" and the button on the right;
Structure module consisting of three containers, each containing a product card;
👍 Good to know
It is crucial to have all those modules saved in your project. Once they are saved, we extract their respective IDs.
To generate an email message like the one described, we prepare the following request based on the module type (static or dynamic).
The query structure:
// QUERY STRUCTURE
{
dataSources: DataSourceDto[],
transformers: TransformerDto[],
composers: ComposerDto[],
templateId: Long,
emailId: Long,
emailName: String,
title: String,
preheader: String
}
JSON sample:
{
"dataSources": [
{
"name": "API_canonical",
"type": "RAW",
"value": [
{
"id": "structure_with_hero_section"
},
{
"id": "structure_with_title_and_cta"
},
{
"id": "structure_empty_3_containers",
"content": [
{
"id": "product_card",
"values": {
"url": "https://viewstripo.email",
"p_image": "https://lgjfwj.stripocdn.email/content/guids/CABINET_92f0b5c5eb2d68625d8a552a86d34e09/images/rgb.png",
"p_price": "$15.00",
"p_description": "Son Ipsum is simply dummy text of the typesetting industry."
}
},
{
"id": "product_card",
"values": {
"url": "https://viewstripo.email",
"p_image": "https://lgjfwj.stripocdn.email/content/guids/CABINET_92f0b5c5eb2d68625d8a552a86d34e09/images/rgb_2.png",
"p_price": "$35.00",
"p_description": "Son Ipsum is simply dummy text of the typesetting industry."
}
},
{
"id": "product_card",
"values": {
"url": "https://viewstripo.email",
"p_image": "https://lgjfwj.stripocdn.email/content/guids/CABINET_92f0b5c5eb2d68625d8a552a86d34e09/images/rgb_1.png",
"p_price": "$65.00",
"p_description": "Son Ipsum is simply dummy text of the typesetting industry."
}
}
]
},
{
"id": "structure_empty_3_containers",
"content": [
{
"id": "product_card",
"values": {
"url": "https://viewstripo.email",
"p_image": "https://lgjfwj.stripocdn.email/content/guids/cab_pub_7cbbc409ec990f19c78c75bd1e06f215/images/92561542727925102.png",
"p_price": "$24.00",
"p_description": "Son Ipsum is simply dummy text of the typesetting industry."
}
},
{
"id": "product_card",
"values": {
"url": "https://viewstripo.email",
"p_image": "https://lgjfwj.stripocdn.email/content/guids/cab_pub_7cbbc409ec990f19c78c75bd1e06f215/images/Sale_Percent_Green.png",
"p_price": "$31.50",
"p_description": "Son Ipsum is simply dummy text of the typesetting industry."
}
},
{
"id": "product_card",
"values": {
"url": "https://viewstripo.email",
"p_image": "https://lgjfwj.stripocdn.email/content/guids/cab_pub_7cbbc409ec990f19c78c75bd1e06f215/images/51151542728444172.png",
"p_price": "$65.00",
"p_description": "Son Ipsum is simply dummy text of the typesetting industry."
}
}
]
}
]
}
],
"transformers": [],
"composers": [],
"templateId": 12345678,
"emailName": "API_doc_canonical"
}Please be advised:
The "templateId" parameter may be taken directly from your prepared Template with dynamic area:
After generating the email will be uploaded in the "Email Messages" tab:
Appendix.
The description of the fields are:
✍️ Please note!
Definition of fields: M — mandatory, O — optional;
You should not send optional fields in the request if you want to keep them empty.
dataSource (M)
The sources of the data, that should be used for email template generation.
DataSourceDto description
{ name: String, //M type: String, //M value: Object //M }where:
name — any name of the data source;
type — currently we do support 2 types:
RAW — in this case, the data should be placed directly in the value field;
LINK — the data will be loaded from the specified URL in the value field;
value — the data of the source or the URL.
Read more about the data source formats with examples in Appendix C.
transformers (O)
The list of transformers that may be applied to the initial data to generate an email.
TransformerDto description
{ type: String, //M source: String, //O outputSource: String, //O config: JSON //M }where:
type — the type of transformers. Read more about supported transformer types in Appendix A;
source — optional field, the name of the source to which this transformer should be applied. If it is not specified, the first one will be used;
outputSource — optional field, the name of the destination source where the converted data will be written after its modification by this transformer. If it’s not specified then results will be written to the initial source;
config — the configuration of the transformer. Each transformer has own format of configuration. Read more about supported transformers in Appendix A.
composers (O)
The list of composers used for mapping the data from the data source with appropriate template area within email template.
ComposerDto description
{ type: String, //O source: String, //O templateArea: String //O }where:
type — an optional field, this is the type of a composer. There are only 2 supported types: “canonical” (used by default) and “plain”.
The “canonical” is used to match the data and the template's auto-generation area when the data source is the canonical JSON.
The “plain” is used to match the data and the auto-generation area of the template when the data source is a plain text that needs to be imported the way it is without any modifications.
source — an optional field, the name of the source from which the data should be taken and applied to template area defined below. If it’s not specified then the data will be taken from the first source;
templateArea — an optional field. This is the zone identifier in the template where to insert the records. If it’s not specified then the first found zone is used.
templateId (M)
This is an ID of a template with the auto-generated area. This template will be used for an email generation. Please note that this template should be yours (saved in the project you have access to), not a basic or a public one.
To view all your templates please go to the Templates menu within Stripo account.
emailId (O)
In case you want to override an already existing email template, please specify its ID here. If this field is empty than a new email will be created.
emailName (O)
This is the name that will be given to a generated email.
If the field is empty then the name of a template will be used as a name of the generated email.
For more details, please follow here.
Thank you for taking the time to read our articles. We hope you will find this information helpful.
If you have any additional questions, please email us at support@stripo.email.
We would be glad to talk with you.