First steps
User Data
- Responsive Email Editor Review
- Designing your email
- Creating Synchronized Modules
- Setting Up Responsive Email Design
- Setting Up Smart Containers
- Creating a Gmail Promotions Annotation
- Adding The Rollover Effect
- Adding Anchor Links
- Module Library
- Adding a Table to an Email
- Adding Custom Fonts
- Creating CTA Button
- Working with Images
- Creating Timer
- Using AI in the Email Editor
Omnichannel
- Setting Up Widgets for Your Site
- Widget Calling
- Setting Up Locations for the Widget Calling Rules
- Storing data from widgets to contact fields
- Using Annoyance Safeguard
- Actions After Form Submission
- Replacing Double Opt-In System Workflow
- Creating Pop-ups via Google Tag Manager or WordPress
- Sending Yespo Widget Events to Google Analytics
- Using A/B Tests for Widgets
- Collecting Contact Information Using Request Forms
Automation
- Building and Editing Workflows
- Configuring Workflow Start/Stop Conditions
- Start Block
- Popular Blocks
- Message Blocks
- Using One from Many Message Block
- Contact Blocks
- Conditions Blocks
- Other Blocks
- Message to Segment Blocks
- Time Blocks
- Advanced Workflow Block Parameters
- Setting Up Allowed Send Time
- Using Workflow Launch History
- Webhook Workflows
- Workflow Troubleshooting
- Double Opt-In
- Welcome Сampaign
- Welcome Series Segmented by Category
- Launching a Workflow After a Contact Import
- Regular Workflow for a Segment
- Birthday Campaign
- Linking Workflow to the Button
- Using Variables from Order in Workflow
- Collecting Order Feedback
- Customer Reactivation
- Sending Extra Campaigns
- Sending Reminders at the Time Specified by the User
- Sending Campaign to Those Who Did Not Open the Previous One
- Using A/B Tests In Workflows
Personalization
Analytics
- Email Campaign Report
- Web Push Campaign Report
- Viber Campaign Report
- Mobile Push Campaign Report
- App Inbox Campaign Report
- Telegram Campaign Report
- In-App Report
- Widget Report
- Triggered Campaign Report
- AMP Campaign Report
- SMS Campaign Report
- Multilingual Campaign Report
- Setting up UTM Tags
- Revenue from Campaigns
- Tracking Campaign Performance in Google Analytics 4
- Message Analytics
Multilanguage Campaigns
Events and Behaviour Tracking
Recommendations
API
Security and Compliance
FAQ: Integrating with API
See answers to the most common questions about Yespo API integration.
You can find all technical documentation on the data format for calling API requests here.
How to Check API for Correct Performance and Valid Access Options
For example, you can get information about your account using the Get account info method. Follow these steps:
1. Generate an API key and copy it to your clipboard.
2. Go to the https://docs.yespo.io/reference/getaccountinfo-1 page.
3. Enter the username and password that is the copied API key above the example request.
4. Click Try it!
You should see your username and your organization name in the response:
How to Unsubscribe a Contact Who Has Unsubscribed in the Personal Account on the Site
There are two API resources to manage unsubscribes — Add emails to unsubscribed list and Remove emails from unsubscribed list.
Important
The method unsubscribes not contacts but their email addresses (other channels — SMS, Viber, Web Push — remain active). All contacts within the organization who may use these email addresses will stop receiving bulk emails from you.
The request body would look as follows:
{
"emails" : [ "test1@mail.com", "test2@mail.com" ]
}
where emails — the email addresses that will be marked as unsubscribed.
The Remove emails from unsubscribed list request body is similar to the previous method: you enter the email addresses that will be deleted from the unsubscribed.
Let's look at working with the Remove emails from unsubscribed list method:
1. Go to the https://docs.yespo.io/reference/deletefromunsubscribed-1 page.
2. Click ADD STRING in BODY PARAMS and enter the addresses of unsubscribed contacts in the strings.
3. Click Try it!
If the addresses in the request have been unsubscribed from your Yespo account, they will be removed from this list.
How to Use Dynamic Content in Messages
There are two ways to implement sending an email with dynamic content:
- Using a workflow
- Using the Send prepared message method
Using a Workflow
Use the Generate event API method to insert the data dynamically from the request body into the message. The array params may contain a random number of parameters:
{
"name": "field name",
"value": "field value"
}
Use Velocity variables to insert dynamic data into a message.
For example, you call the request in the following format:
{
"eventTypeKey": "testEvent",
"keyValue": "example@email.com",
"params": [{
"name": "discount",
"value": "5%"
},{
"name": "link",
"value": "https://example.site.com/items_for_sale"
}
]
}
The message must use the variables $!data.get('discount') and $!data.get('link'), instead of which the data from the request will be substituted.
To insert the content sent by the Generate event method into the body of the message, prepare a workflow using this message, which the corresponding event will trigger. Details >
Using the Send Prepared Message Method
This method involves sending messages without using a workflow. The {id} in the link https://yespo.io/api/v1/message/{id}/smartsend is the identifier of the message into which the data will be inserted when sent to the recipient.
Minimum request body:
{
"recipients" : [ {
"locator" : "...",
"jsonParam" : "..."
} ]
}
where:
- recipients are the array of the message recipients’ contact data;
- locator is a recipient. For example, an email address for emails and a phone number for SMS or Viber messages;
- jsonParam is data in the JSON format to insert in the message.
This method allows for generating different content for each recipient. The entered data is organized in "email + a set of parameters” pairs. The parameters are entered as a random JSON structure, and all fields are assigned $data.get('field_name').
Using this method, you can:
- Set the condition for displaying a block of HTML code: #if($data.get('field_name').equals('0')) ... #end.
- Loop through array elements: #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... # end.
- Perform arithmetic operations with field values in the body of the email.
Note: the double quotes inside the JSON structure with the parameters should be modified by an escape character: "jsonParam" : "{\"field1\":\"value1\", ... }".
For more information, see the article Using the Send prepared message API method.
How to Use Events for Triggers
Triggered campaigns can be launched using the Generate event API method. This method is suitable for creating custom events; follow the link for more details.
We also recommend using the Generate event method to transfer orders. Manual >
How to Pass Orders via API, e.g., for Their Confirmation
You can also use the Add orders method to pass orders. One request can contain up to 1,000 orders. Pass the array of items with the data on these products in orders to insert products in emails. You may not pass the array if you don't insert the product data in emails or pass orders only for RFM analysis.
The standard request body looks as follows:
{
"orders": [{
"externalOrderId": "100500",
"externalCustomerId": "12345",
"totalCost": 1000,
"status": "INITIALIZED",
"date": "2017-03-08T09:30:00+02:00",
"email": "mail@example.com",
"phone": "380942583691",
"firstName": "John",
"lastName": "Smith",
"currency": "USD",
"shipping": 10,
"discount": 0,
"deliveryMethod": "express",
"paymentMethod": "cash",
"deliveryAddress": "First str. 1",
"items": [{
"externalItemId": "200600",
"name": "Super Device",
"category": "devices",
"quantity": 1,
"cost": 990,
"url": "http://example.com/item/200600",
"imageUrl": "http://example.com/item/200600/image.png",
"description": "High quality"
}]
}]
}
Each order must contain the following obligatory fields:
The response to a successful request will have the 200 status.
You can use several statuses for orders:
- INITIALIZED for a newly created order.
- IN_PROGRESS for an order being delivered.
- DELIVERED for a paid and delivered order.
- CANCELlED for cancelled orders.
Important
Only orders with the DELIVERED status are used for RFM analysis.
To update the status or other order details, pass the updated order with the same externalOrderId. The system uses this parameter to determine the uniqueness of orders.
To check whether the order has been sent into the system and whether the fields have been passed correctly, go to Automation → Orders. Click the order to see all the fields in the JSON format.
More about using order information in emails >
How to Get a Sent Status for a Message via API
Single messages are sent in the asynchronous mode via the following methods:
After an API request is called, your message is scheduled for sending and is sent within seconds.
The body of the response looks as follows:
{
"id": "0",
"results": {
"id": "0",
"locator": "test@mail.com",
"status": "OK",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
}
}
To get the status of the message sent via any channel, call a request of the Get single message status method.
Ids — the identifiers requestId separated by a comma.
The request body looks as follows:
{
"results": {
"status": "DELIVERED",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",
"failed": "false",
"delivered": "true"
}
}
How to Integrate Subscription Form via API
Yespo offers built-in functionality for creating widgets without additional API settings.
To integrate a subscription form created using a third-party service, call the request using the Subscribe a contact method. The minimum request body looks like this:
{
"contact" : {
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
}
}
A contact with an email address will appear in the system.
To set the contact name, add the firstName field in the contact object to the request body:
{
"contact" : {
"firstName" : "...",
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
}
}
To specify which segments the subscribed contact should be in, add the groups field to the request — an array of string values for segment names. If any segments do not exist in the system, they will be created automatically:
{
"contact" : {
"firstName" : "...",
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
},
"groups" : [ "Subscribers" ]
}
Two event types are automatically generated in the system after the call:
- subscribeFromAPI – in case of creating a new contact;
- subscribeUpdateFromAPI – if such a contact already exists.
You can see these events in the Triggers → Event history section.
Any type of event can be associated with a workflow launched when the event is generated. We recommend sending an email to confirm a new contact subscription.
To ensure a new contact has been created, go to Contacts → All contacts section and enter the contact ID in the search field.
You will see that the contact's email is grayed out, meaning it is inactive and requires confirmation from the owner.
It is impossible to send newsletters to such addresses; they can only receive subscription confirmation emails and other trigger messages, for example, an abandoned cart email or confirmation of a completed order.
How to Pass Additional Field Values via API
Let's look at updating additional fields using the Add/update contacts method. The standard request body looks as follows:
{
"contacts": [{
"channels": [{
"type": "email",
"value": "test@mail.com"
}],
"fields": [{
"id": 12345,
"value": "..."
}]
}],
"customFieldsIDs": [12345]
}
where
- channels is a list of the contact’s media channels (in the example, one media channel — email address — is passed);
- fields is a list of additional fields passed in pairs: field ID + value.
There are two ways to get all the IDs available in your account.
The first is to view the identifiers in the account menu → Settings → Additional fields.
The second is to call the Get the list of catalogs method. This parameterless method will return you a structure like this:
{
"addressBook": {
"addressBookId": "7200",
"name": "Main",
"fieldGroups": {
"name": "Personal",
"fields": [
{
"id": "15867",
"name": "Birthday",
"description": {
"type": "date",
"required": "false",
"readonly": "false"
}
},
{
"id": "15868",
"name": "Gender",
"description": {
"type": "combobox",
"allowedValues": {
"possibleValues": [
"M",
"F"
]
},
"required": "false",
"readonly": "false"
}
}
]
}
}
}
The fields list is a collection of all your additional fields. In addition to other information, each object in this list contains a field identifier that must be used when passing its value.
How to Test API Using Postman
Postman is a popular API testing tool. It provides a user-friendly interface for creating, sending, and tracking requests.
To get started with Postman, download and install it on your computer.
Testing the Get Account Info Method
1. Select Basic Auth in the parameters, Authorization tab, Type line:
2. Log in:
- enter any value in the Username field,
- enter the value of your API key in the Password field.
3. Select the GET method and enter the https://yespo.io/api/v1/account/info link.
4. Click the Send button.
You should see your username and your organization name in the response:
{
"userEmail": "api-user162065",
"organisationName": "ExamleName"
}
Testing the Remove Emails from Unsubscribed List Method
1. Select the POST request method and enter the https://yespo.io/api/v1/emails/unsubscribed/delete link.
2. Select raw and JSON data transfer format in the Body section.
3. Specify the request body in the following format:
{
"emails" : [ "...", "..." ]
}
4. Click Send.
If the addresses in the request have been unsubscribed from your Yespo account, they will be removed from this list.
Testing the Generate Event v2 Method
1. Select the POST request method and enter the https://yespo.io/api/v2/event link.
2. Select raw and JSON data transfer format in the Body section.
3. Specify the request body in the following format:
{
"eventTypeKey": "create_contact",
"keyValue": "site@com.net",
"params":
[
{
"name": "email",
"value": "site@ukr.net"
},
{
"name": "phone",
"value": "380501234567"
},
{
"name": "externalCustomerId",
"value": "AV13760"
},
{
"name": "json",
"value":
{
"profileInputs":
[
{
"profileInputId": 10001,
"value": "2020-11-23"
}
]
}
}
]
}
4. Click Send.
A successfully submitted request will appear in the event history in your Yespo account.