Syntax and rules

Overview

A reference to keep open while writing instructions. It covers the options you can use, when saving is rejected, limits, and advanced examples.

Available syntax

Syntax	Description	If omitted
`:save`	Name to store the response under. Read JSON with `{{ name.field }}`	JSON is stored in `connected`, and plain text is printed where the instruction is
`:method`	`get` or `post`	`get`
`:body`	Data to send with POST. Must be used with `:method post`	Called with no data
`:content_type`	Format of the data you send. Use `application/json` for a JSON body	Form format (`application/x-www-form-urlencoded`)
`:headers`	Additional headers, written as a JSON object. Example: `:headers {"X-Store-Id": "123"}` If it isn’t valid JSON, the call isn’t made and is treated as failed. For authentication headers, use a registered credential	Default headers only
`:basic_auth`	Name of a credential registered as Basic	Called without authentication
`:auth_credentials`	Name of a credential registered as Token	Called without authentication
`:cache_max_age`	How long to reuse the response, in seconds. If the call returns the same value for every recipient, set it longer to reduce calls	Default cache rules (see Set up response reuse)
`:no_cache`	Calls fresh every time. Use it for values that must always be current, such as stock	Cache is used
`default:`	Text to show when the value is empty (an existing personalized message filter)	Sent blank
`{% abort_message %}`	Doesn’t send to this recipient	Sent even if blank

When saving is rejected

Rejected when	How to fix
Liquid syntax error, unsupported filter or tag	Check that brackets are paired and filter names are correct
Unsupported option or invalid option value	`:method` accepts only get or post Write `:cache_max_age` in seconds (for example, `3600`) `:retry` isn’t supported yet (coming soon)
Too many calls in a message	Write no more than 3 across all fields, including subject and content.
Instruction inside a for loop	Call once outside the loop and loop over the response array (see example 4 below)
Personalization variable in the domain of the request URL	You can’t use personalization variables in the domain of the request URL Keep the domain fixed and use variables only in the path or query
Saved name used without a field	Include the field, as in `{{ point.amount }}` instead of `{{ point }}`
Credential issue	Check that the name is registered, that the type (Basic or Token) matches the option (`:basic_auth` or `:auth_credentials`), and that the allowed domain exactly matches the request URL

Limits

Item	Limit
Calls per message	3 across all fields, including subject and content · Each instruction counts as one. The same URL written again in a different field counts separately · Instructions inside `{% if %}` branches all count, whether or not they run · In journey automation, 3 per message action
Maximum wait per call	2 seconds
Response size	1MB
Request URL length	2048 characters after variables are filled in
Response cache duration	· GET: 5 minutes by default · POST: only when `:cache_max_age` is set · `:cache_max_age` range: 300 seconds (5 minutes) to 14400 seconds (4 hours). Values outside the range are set to the nearest limit
Credentials	10 per project

Advanced examples

Examples to refer to once you know the basics.

Example 1. Use the same value in the subject and content

A name saved with :save can only be used in the field where the instruction is written. To use it in another field, such as the subject and the content, write the instruction in each field. If the URL is the same, the cached response is reused.

Subject

{% connected_content https://api.example.com/products/{{ tags.wishlist_sku }} :save product %}The price of {{ product.name }} on your wishlist just dropped.

Content

{% connected_content https://api.example.com/products/{{ tags.wishlist_sku }} :save product %}Get it now for {{ product.price | number_with_delimiter }}.

Example 2. Use one response in the next call

Instructions run from top to bottom, so you can use a value saved earlier in the next request URL. The next call starts only after the previous one finishes, so wait times add up.

{% connected_content https://api.example.com/me?uid={{ userId }} :save me %}
{% connected_content https://api.example.com/orders/{{ me.id }} :save orders %}
{{ me.name }}, you have {{ orders.total }} orders

Example 3. Call a different API depending on a condition

You can call inside {% if %}, and you can use the same name on both sides. It holds the response from whichever side actually ran.

{% if tags.vip %}
  {% connected_content https://api.example.com/vip-deals :save deals %}
{% else %}
  {% connected_content https://api.example.com/normal-deals :save deals %}
{% endif %}
Today's deal: {{ deals.title }}

Example 4. Show a list from the response with a loop

Call the instruction once outside the loop, then show the returned list with a loop.

{% connected_content https://api.example.com/reco?uid={{ userId }} :save reco %}
Recommended for you:

{% for item in reco.items %}
- {{ item.title }} {{ item.price | number_with_delimiter }}
{% endfor %}