Go to Stripo
All Collections
Editor Questions
Additional Features
How simply create emails with Stripo API with canonical JSON
How simply create emails with Stripo API with canonical JSON
In this article you will find out how to create emails with Stripo API with canonical JSON
Oleh Tokariev avatar
Written by Oleh Tokariev. Updated over a week ago

Any user who designs similar emails sends it 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.

To begin with we start from preparing a template and will generate an email on it's 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.

However, let's go in order of creation.

At first in order to start generating an email using the Stripo API, we will distribute the preparation by stages.

Stage 1: We save our elements: banners and product cards into modules.

I saved this simple banner as a module:

And set it's unique ID: structure_banner_top

I have got a structure with 3 containers with product cards and first of all I need to create and save as a module the empty structure with 3 containers as well. The product cards will be defined and filled into these containers.

And set it's unique ID: empty_structure_3_containers

Let's prepare product card as well.

The product cards need to have Smart properties to be able to automatically replace data in it.

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.

Basically we need to set unique variables for product card's elements:

Then set relevant unique classes to these elements in code:

Save only one smart container as a module and set it's ID: product_card

Save other need structures and modules and set their ID.

First Stage has DONE!

Stage 2: Create an auto-generation area within the desired template for the email generation.

Let's copy your template. Please kindly leave your need header and footer in it since they will be static. And then please remove all content area. The result should look like here:

The easiest item is the last one. Please, choose the template for your auto-generation emails. This template should be yours (saved in the project you have access to), not the basic or public. Basically, it may have some static elements like Header and Footer, etc. AND it should have at least one stripe with a special class, needed to determine the place where exactly the content should be inserted in when the Generate Email method is called.

For this purpose, please add an empty stripe with one column and add the esd-email-gen-area="name_of_area" class to the td tag of the stripe in the code editor where the name_of_area is the given name.

Example of the stripe with area for email auto-generation, called products-area.

<td class="esd-stripe" align="center" esd-email-gen-area="products-area">

Done!

Stage 3: JWT token for authentication of all REST API calls

  • Get a JWT token for authentication of all REST API calls.

To generate a JWT token please move to your Project settings > scroll down to Access to the REST API and copy 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.

  • Download 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:

To do so please click on a "+" on the left-top corner of a screenshot and create a New collection.

Then set 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 a 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.

Stage 4: Starting to generate emails using Postman

According to the Stage 3 please create another New Collection by clicking on "+" icon

Then set POST method and add /email to the API URL

( https://stripo.email/emailgeneration/v1/email )

Please set same two keys in the Headers tab:

Key

Value

Stripo-Api-Auth:
YOUR_JWT_TOKEN
Content-Type
application/json

Then please switch with the tab Body, choose raw type and you are ready to create your canonical JSON.

Description of structure of needed parameters for the JSON:

Scroll down to the Appendix for a description of each following fields.

// FORMATTING AND FILLING IN THE DATA SOURCE
{
"dataSources": [
{
"name": "Test source for Demo", // DIFFERENT NAME
"type": "RAW",
"value": {
}
}
],
"transformers": [],
"composers": [],
"templateId": "555555", // THE ID OF YOUR TEMPLATE WITH esd-email-gen-area="products-area"
"emailName": "Test # 1" // THE NAME OF YOUR FURTHER GENERATED EMAIL
}

For more details please follow here.

See our sample of a JSON:

// INSERTED DATA
{
"dataSources":[
{
"name":"Test source for Demo",
"type":"RAW",
"value":[
{
"id":"structure_top_banner"
},
{
"id":"structure_title_dynamic",
"values":{
"p_name":"BEST DEALS!"
}
},
{
"id":"empty_structure_3_containers",
"content":[
{
"id":"container_product",
"values":{
"url":"https://viewstripo.email",
"p_name":"Leather Jacket",
"p_image":"https://hpy.stripocdn.email/content/guids/CABINET_9239c093ecdd07579968a78fedaa6e32/images/98571572875380318.png",
"p_price":"$199",
"p_old_price":"$399"
}
},
{
"id":"container_product",
"values":{
"url":"https://viewstripo.email",
"p_name":"Red shirt",
"p_image":"https://hpy.stripocdn.email/content/guids/CABINET_5317ac85fc16b8abe6584e030563da53/images/74801572874593362.png",
"p_price":"$99",
"p_old_price":"$149"
}
},
{
"id":"container_product",
"values":{
"url":"https://viewstripo.email",
"p_name":"Checkered shirt",
"p_image":"https://hpy.stripocdn.email/content/guids/CABINET_5317ac85fc16b8abe6584e030563da53/images/1191572880345345.png",
"p_price":"$99",
"p_old_price":"$149"
}
}
]
},
{
"id":"structure_discover_button"
}
]
}
],
"transformers":[
],
"composers":[
],
"templateId":"591945",
"emailName":"Test # 1",
"title": "Your title",
"preheader": "Your preheader"
}

The query structure:

// QUERY STRUCTURE
{
dataSources: DataSourceDto[],
transformers: TransformerDto[],
composers: ComposerDto[],
templateId: Long,
emailId: Long,
emailName: String,
title: String,
preheader: String
}

Appendix. The description of the fields are:

Please note!

  • Definition of fields: M — mandatory, O — optional;

  • You should not send optional field 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.

If you have any questions, please email us at support@stripo.email

Did this answer your question?