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 project settings.
Scroll down to Access the REST API and generate it.
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 templates creation and planning 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 for using, 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
Let's check that the token is valid:
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.
For more info about status codes, please follow here.
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:
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 Module Library 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. 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:
link to the item on your website;
an image of the product;
its title;
the short description;
and a price.
A configuration tab will be created for each added variable; in this case, there will be 5 tabs.
Next, configuration rules need to be set up to map the content values for these variables. Please use the UI constructor to specify each variable's content location within this module.
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
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.
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, and explanation text below.
Title module showcasing the text "Top Items" and the button on the right.
Structure module consisting of three containers, each containing a product card.
A structure with a "See More" button at the bottom.
👍 Good to know
Just a friendly reminder that 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://my.store.com/1",
"p_name": "Burger Deluxe",
"p_image": "https://stripocdn.email/content/guids/CABINET_bb3fcdd24c9db8847ad38a4aed1beecdc1b0954412c0bce53f279d420cef8bac/images/g508c2454742bc875d5b894928707586f6f84c72f9394d53dc84ae96c3dc17c0ca6602b92d982eb976a550bd2560065.jpeg",
"p_price": "$9.99",
"p_description": "Classic beef burger with special sauce."
}
},
{
"id": "product_card",
"values": {
"url": "https://my.store.com/2",
"p_name": "Crispy Chicken",
"p_image": "https://stripocdn.email/content/guids/CABINET_bb3fcdd24c9db8847ad38a4aed1beecdc1b0954412c0bce53f279d420cef8bac/images/g6b5990d1f0152cc8abf1a15e3e67eee115aedce8899879a8d0921fa07ef458605bcca5441bffb2a1fb085b3b17895c.jpeg",
"p_price": "$8.99",
"p_description": "Tender fried chicken with a crispy coating."
}
},
{
"id": "product_card",
"values": {
"url": "https://my.store.com/3",
"p_name": "Cheese Pizza",
"p_image": "https://stripocdn.email/content/guids/CABINET_bb3fcdd24c9db8847ad38a4aed1beecdc1b0954412c0bce53f279d420cef8bac/images/g62bebef9194ff3ce2b3dc3c486eadf1dc13daf2866ff31ac97f50ecc38f280d8e6ad47e7a95bd32b71ff4152d740f8.jpeg",
"p_price": "$10.99",
"p_description": "Traditional cheese pizza with a thin crust."
}
}
]
},
{
"id": "structure_empty_3_containers",
"content": [
{
"id": "product_card",
"values": {
"url": "https://my.store.com/4",
"p_name": "Spicy Wings",
"p_image": "https://stripocdn.email/content/guids/CABINET_bb3fcdd24c9db8847ad38a4aed1beecdc1b0954412c0bce53f279d420cef8bac/images/g73c4730dff9673ada7830cd31ec8383e917145e313fade955f2eb4fb97811ab713a7f30a900ad2ace427938bf36279.jpeg",
"p_price": "$7.99",
"p_description": "Hot chicken wings with a tangy sauce."
}
},
{
"id": "product_card",
"values": {
"url": "https://my.store.com/5",
"p_name": "Veggie Wrap",
"p_image": "https://stripocdn.email/content/guids/CABINET_bb3fcdd24c9db8847ad38a4aed1beecdc1b0954412c0bce53f279d420cef8bac/images/g6f1f0b6392ed7d69c9963709df64027471ad48b367300e06619b9e308365a6e9a44f918c31c8e77ad259ff7285a74e.jpeg",
"p_price": "$6.99",
"p_description": "Fresh vegetable medley wrapped in a tortilla."
}
},
{
"id": "product_card",
"values": {
"url": "https://my.store.com/6",
"p_name": "Loaded Fries",
"p_image": "https://stripocdn.email/content/guids/CABINET_bb3fcdd24c9db8847ad38a4aed1beecdc1b0954412c0bce53f279d420cef8bac/images/ge5457c2f851237616836280c07f5bc4091bb21d00fc4b560749d34692c35b7260e521ea1ba89fdc47ce4cc4c82f74b.jpeg",
"p_price": "$5.99",
"p_description": "Crispy fries topped with melted cheese."
}
}
]
},
{
"id": "structure_with_cta"
}
]
}
],
"transformers": [],
"composers": [],
"templateId": 12345678,
"emailName": "API_doc_canonical"
}
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.