The API trigger block starts an automation scenario when data is received from an external source — your website, app, CRM, or platforms like Shopify.
The received data can then be used to personalize your emails with dynamic content based on customer or subscriber actions. Depending on your setup, you can use the API trigger block to send automated drip campaigns, transactional emails, or personalized recommendations.
Set up API trigger block
To start sending automated email campaigns with dynamic content, create a scenario with the API trigger block in the omnichannel automation scenario editor and set up integration with the external source.
Create new scenario
Go to Scenarios and create a new scenario. Select the Triggers tab on the panel at the bottom of the scenario builder and drag the API trigger block into the work space.
Then, build the rest of the scenario using available blocks and adding email designs to create an email sequence.
For example, you can set up a welcome sequence for new subscribers.
First, the scenario sends a welcome email. After three days, a follow-up email with a discount is sent to subscribers who haven’t clicked the link to the shop.
Once everything is set, run the scenario — otherwise, the data received via API won’t be processed.
Set up integration with external source
To set up integration with an external source such as a website, app, Webflow, or Shopify, you will need a developer. They will set up API integration to send POST requests to the URL(1) generated by the API trigger block.
The data sent in requests must be in JSON format.
At a minimum, each request must include a customer email address or phone number (2), as Selzy uses this information to identify recipients. You can also include more data relevant to your scenario, such as: customer name, promo code, list of products or services, order total, etc.
Example request:
POST https://api.selzy.com/en/api/triggerBlock/{blockId}
Content-Type: application/json
{
"email": "hello@example.com",
"products": [
{
"name": "Coffee mug",
"link": "https://example.com/link1"
},
{
"name": "Coaster",
"link": "https://example.com/link2"
}
]
}
Server responses
If the request is successfully sent, you will receive the following response:
{
"success": true
}
If the request is missing both email address and phone number, the server will return the following error:
{
"error": "Error ID:... Can't define contact",
"code": "invalid_arg"
}
If the API trigger URL contains an incorrect API trigger block ID, the server will return the following error:
{
"error": "Error ID:... Invalid UUID string",
"code": "invalid_arg"
}
Use received JSON data in email campaigns
JSON data received from an external source not only triggers your scenario but also allows you to personalize your emails. For example, you can address your customers by name, list their ordered products, or include a delivery date.
To personalize emails, process the received JSON data using Liquid, a templating language created by Shopify, and then insert Liquid code into Selzy’s email builder. Both the subject line and email body support dynamic content.
Process JSON data using Liquid
To display dynamic content in your emails, Liquid code must reference variables from incoming API requests.
If you want to further customize the dynamic content, you can use filters and tags that control how the received data appears.
Variables
Variables are included in the incoming API requests and their format entirely depends on your external source’s setup.
To display the received data in your email, wrap variables in double curly brackets: {{ variable }}. Make sure to specify a unique API trigger block key before the variable. This tells the system where to find the data for your email.
You can edit the key in the API trigger block settings. However, if you change the key, make sure to update your Liquid code with the new key, otherwise the received data won’t appear in the email.
| Example API request (JSON) | Liquid code in email content | Final email output |
| {
"email": "hello@example.com", "name": "Ursula" } |
Hello {{ ApiTrigger1.name }}!
Your email: {{ ApiTrigger1.email }} |
Hello Ursula!
Your email: hello@example.com |
| API trigger block | Selzy’s email builder (Code mode) | Recipient’s inbox view |
Filters
Filters allow formatting and customization of dynamic content. For example, the ‘capitalize’ filter converts “john” into “John” if the name is originally stored in lowercase. Filters are applied after variables and are separated by a pipe ( | ) operator.
| Filter | Example API request (JSON) | Liquid code in email content | Final email output |
| capitalize — Converts text to Title Case | { "name": "ursula" } | Hello {{ ApiTrigger1.name | capitalize }}! | Hello Ursula! |
| upcase — Converts text to UPPERCASE | { "promocode": "solstice2025" } | Grab your promo code: {{ ApiTrigger1.promo | upcase }} | Grab your promo code: SOLSTICE2025 |
| downcase — Converts text to lowercase | { "promocode": "SOLSTICE2025" } | Grab your promo code:{{ ApiTrigger1.promo | downcase }} | Grab your promo code: solstice2025 |
| replace —
Finds and replaces all occurrences of specific text in a string |
{
"social_link": "https://twitter.com/example_user" } |
<a href="{{ social_link | replace: 'twitter.com', 'x.com' }}">
Follow us on {{ "Twitter" | replace: "Twitter", "X" }}! </a> |
Follow us on X! |
| default — Provides a fallback value if the variable is empty | { "name": "" } | Hello {{ ApiTrigger1.name | default: "there" }}! | Hello there! |
| date — Formats a date into a specific format | { "delivery_date": "2025-05-01" } | Delivery date: {{ ApiTrigger1.delivery_date | date: "%B %-d, %Y" }} | Delivery date: May 1, 2025 |
You can combine multiple filters to modify a variable in a single step. Filters are applied in order, from left to right, meaning each filter modifies the result of the previous one.
| Example API request (JSON) | Liquid code in email content | Final email output |
| { "delivery_date": "2025-05-01" } | Delivery date: {{ ApiTrigger1.delivery_date | date: "%B %-d, %Y" | upcase }} | Delivery date: MAY 1, 2025 |
Tags
Tags control what dynamic content recipients see.
For most communications related to the customer's cart you will need ‘for’ and ‘if’ tags.
for
The ‘for’ tag is commonly used to show abandoned cart items, recent purchases, or recommended products in emails.
| Example API request (JSON) | Liquid code in email content | Final email output |
| {
"customer": { "email": "ursula@example.com", "cart": [ { "name": "Wireless Headphones", "price": 40.00, "link": "https://example.com/products/wireless-headphones" }, { "name": "Smartwatch", "price": 25.00, "link": "https://example.com/products/smartwatch" } ] } } |
<p>Hey {{ ApiTrigger1.customer.email }},</p>
<p>Here’s what’s in your cart:</p> <ul> {% for item in ApiTrigger1.customer.cart %} <li>{{ item.name }} - ${{ item.price }} - <a href="{{ item.link }}">View Item</a></li> {% endfor %} </ul> |
Hey ursula@example.com,
Here’s what’s in your cart: - Wireless Headphones - $40.00 - View Item - Smartwatch - $25.00 - View Item |
if
The ‘if’ tag controls dynamic content based on specified conditions. It's often used for personalized offers, like subscriber-only discounts, free delivery, or gifts for orders above a certain price.
The ‘if’ tag is often used with comparison (==, !=, >, <, >=, <=) and logic (or, and, contains) operators.
| Example API request (JSON) | Liquid code in email content | Final email output |
| {
"customer": { "email": "ursula@example.com", "cart_total": 65.00, "cart": [ { "name": "Wireless Headphones", "price": 40.00, "link": "https://example.com/products/wireless-headphones" }, { "name": "Smartwatch", "price": 25.00, "link": "https://example.com/products/smartwatch" } ] } } |
<p>Hey {{ ApiTrigger1.customer.email }},</p>
{% if ApiTrigger1.customer.cart_total >= 50 %} <p>Great news! Your order qualifies for <strong>FREE delivery</strong>.</p> {% else %} <p>Add more items to your cart to unlock <strong>FREE delivery</strong> on orders above $50!</p> {% endif %} <p>Here’s what’s in your cart:</p> <ul> {% for item in ApiTrigger1.customer.cart %} <li>{{ item.name }} - ${{ item.price }} - <a href="{{ item.link }}">View Item</a></li> {% endfor %} </ul> |
Hey ursula@example.com,
Great news! Your order qualifies for FREE delivery. Here’s what’s in your cart: - Wireless Headphones - $40.00 - View Item - Smartwatch - $25.00 - View Item |
To learn more about Liquid, check their user documentation. We also recommend trying their live demo to experiment with dynamic content formatting and test code specific to your scenario.
Insert Liquid code into email content
To use the received JSON data, hover over the email preview in the Email block of your scenario and click Edit.
Once the Email builder opens, switch to Code mode.
Insert Liquid code into the correct location of the email code. Make sure to reference the unique API trigger block key, otherwise the received data won’t appear in the email.
Test scenario with API trigger
You can test scenarios with the API trigger block by simulating API requests using Postman or similar API testing tools.This way, you can validate your scenario and preview the email campaign as subscribers would see it — without needing live data.
To start testing, create a new POST request in Postman. Copy the POST URL from the API trigger block and paste it into the request field. Make sure to set the request format to JSON.
Add a JSON body with the required variables for the API trigger. For the email address, use one you have access to so you can view the campaign. Send the request to test how the scenario responds.
If the scenario functions correctly, you will receive an email to the address included in the request.
Errors
If an omnichannel automation scenario with an API trigger block does not function correctly or the received data doesn’t appear in emails, start by identifying where the error occurred — whether it’s on the external source’s side, in Liquid, or in Selzy.
Below, you will find a list of common errors and possible solutions:
- Integration errors. If a scenario in Selzy does not receive data or receives it with errors, check the integration on the external source’s side and make sure.
- The correct URL from the API trigger block is used.
- The POST request contains an email address or phone number.
- Data is sent in JSON format.
Please note that the API trigger block does not produce specific errors on Selzy’s side, as it only receives data and starts scenarios. If the setup appears correct but is still not working, you will likely need assistance from your developer or the platform you are integrating Selzy with.
- Liquid code errors. If the received data doesn’t appear in emails, make sure:
- Variables and the API trigger block key are referenced correctly.
- There are no typos or unnecessary spaces.
- The number of curly brackets is correct, and the filters are applied properly
You can use Liquid Playground to test whether your Liquid code produces the correct output and refer to their user documentation to identify and fix formatting issues.
- Scenario errors. If a scenario in Selzy does not receive data or does not send emails, check the scenario settings and make sure it is active.
Go to the list of your scenarios, find the scenario that is not functioning properly, and open the detailed statistics page. There you will find the scenario current status, key performance metrics and errors.
If the scenario is missing blocks or content, it is likely that you have not saved the latest changes. Go back to the scenario editor and update the scenario by clicking Update and run at the top of the screen.
If you are having issues with identifying or fixing scenario errors please contact Selzy’s support team for assistance.
