Making a Connected Content API call

Use Connected Content to insert any information accessible by API directly into messages you send to users. You can pull content either directly from your web server or from publicly accessible APIs.

This page covers how to make Connected Content API calls, advanced Connected Content use cases, error handling, and more.

Understanding Connected Content call volume

Braze may make the same Connected Content API call more than once per recipient. Common reasons include:

• Email with multiple parts: A single email can trigger separate rendering passes for the HTML body, plain text body, and Accelerated Mobile Pages (AMP) version (if present). Each pass can trigger Connected Content in that part, so one recipient may generate multiple identical or similar calls.
• Validation and retries: Message payloads can be rendered multiple times per recipient for validation, retry logic, or other internal purposes.
• Channel behavior: Connected Content executes when the message is rendered. For in-app messages, the message is rendered at impression time.

If you see more Connected Content calls in your logs than sends or recipients, that behavior is expected. For guidance on reducing load and planning for scale, see Best practices for high-volume endpoints.

Sending a Connected Content call

To send a Connected Content call, use the {% connected_content %} tag. With this tag, you can assign or declare variables by using :save. Aspects of these variables can be referenced later in the message with Liquid.

For example, the following message body will access the URL http://numbersapi.com/random/trivia and include a fun trivia fact in your message:

1
2
{% connected_content http://numbersapi.com/random/trivia :save result %}
Hi there, here is some fun trivia for you!: {{result.text}}

Adding variables

You can also include user profile attributes as variables in the URL string when making Connected Content requests.

For example, you may have a web service that returns content based on a user’s email address and ID. If you’re passing attributes containing special characters, such as the at sign (@), make sure to use the Liquid filter url_param_escape to replace any characters not allowed in URLs with their URL-friendly escaped versions, as shown in the following email address attribute.

1
2
3
Hi, here are some articles that you might find interesting:

{% connected_content http://www.yourwebsite.com/articles?email={{${email_address} | url_param_escape}}&user_id={{${user_id}}} %}

Connected Content requests support GET and POST requests only.

Error handling

If the URL is unavailable and reaches a 404 page, Braze will render an empty string in its place. If the URL reaches an HTTP 500 or 502 page, the URL will fail on the retry logic.

If the endpoint returns JSON, you can detect that by checking if the connected value is null, and then conditionally abort the message. Braze only allows URLs that communicate over port 80 (HTTP) and 443 (HTTPS).

Unhealthy host detection

Connected Content employs an unhealthy host detection mechanism to detect when the target host experiences a high rate of significant slowness or overload, resulting in timeouts, too many requests, or other outcomes that prevent Braze from successfully communicating with the target endpoint. It acts as a safeguard to reduce unnecessary load that may be causing the target host to struggle. It also serves to stabilize Braze infrastructure and maintain fast messaging speeds.

If the target host experiences a high rate of significant slowness or overload, Braze will temporarily halt requests to the target host for one minute, instead simulating responses indicating the failure. After one minute, Braze will probe the host’s health using a small number of requests before resuming requests at full speed if the host is found to be healthy. If the host is still unhealthy, Braze will wait another minute before trying again.

If requests to the target host are halted by the unhealthy host detector, Braze will continue to render messages and follow your Liquid logic as if it received an error response code. If you want to ensure that these Connected Content requests are retried when they’re halted by the unhealthy host detector, use the :retry option. For more information on the :retry option, see Connected Content retries.

If you believe the unhealthy host detection may be causing issues, contact Braze Support.

Rate limits (429) versus unhealthy host detection

The following are different mechanisms:

• 429 Too Many Requests: Your endpoint (or an upstream service) is returning this response. It means your server or middleware is refusing traffic, often because it has its own rate limit. Braze does not apply a separate rate limit to Connected Content; Connected Content request volume scales directly with your message delivery speed rate limit. Because messages can be rendered multiple times per recipient (for example, for email HTML, plain text, and AMP), the number of Connected Content requests can exceed that rate limit—do not assume it will be less than or equal to the messages per minute you set. If you see 429s, scale your endpoint or middleware to handle the expected request volume, or lower the campaign or Canvas step rate limit so that fewer messages (and thus fewer Connected Content calls) are sent per minute.
• Unhealthy host detection: A Braze-side safeguard that triggers after a high rate and volume of failures in a one-minute window. The failure count includes 408, 429, 502, 503, 504, and 529 status codes. When triggered, Braze temporarily halts requests to that host and simulates a failure response. This is independent of your own rate limiting. For detection thresholds and more detail, see Troubleshooting webhook and Connected Content requests. To avoid hitting unhealthy host detection, ensure your endpoint can handle the call volume described in Understanding Connected Content call volume and Best practices for high-volume endpoints.

Allowing for efficient performance

Because Braze delivers messages at a very fast rate, ensure your server can handle thousands of concurrent connections so it doesn’t get overloaded when pulling down content. When using public APIs, confirm your usage won’t violate any rate-limiting that the API provider may employ. Braze requires the server response time to be less than two seconds for performance reasons; if the server takes longer than two seconds to respond, the content is not inserted.

For more on planning endpoint capacity and reducing call volume, see Best practices for high-volume endpoints.

Things to know

• Braze does not charge for API calls and will not count toward your given data point usage.
• There is a 1 MB limit for Connected Content responses.
• Connected Content executes when the message is rendered. For in-app messages, the message is rendered at impression time.
• Connected Content calls do not follow redirects.

Best practices for high-volume endpoints

If your messages use Connected Content and you send at high volume, plan for more requests than the number of recipients or sends:

1. Estimate peak load: Use a conservative multiplier when sizing your endpoint or middleware—Connected Content requests can exceed the number of recipients or messages sent. For example, for email a single recipient can generate multiple calls (HTML, plain text, and AMP), so recipients × 2 or × 3 is often used as a conservative estimate.
2. Use caching where appropriate: GET requests are cached by default. For POST requests, add :cache_max_age when the response can be reused for a period (for example, token or content that doesn’t change per request). See Caching responses and the POST caching FAQ below.
3. Set delivery speed rate limiting: Delivery speed rate limiting on campaigns or Canvas steps is the only lever to indirectly limit Connected Content request volume—Braze does not rate limit Connected Content itself. It is only a proxy, and not a perfect one, because Connected Content requests are not 1:1 with messages. Use it to keep message (and thus Connected Content) volume within what your endpoint can handle.
4. Design for idempotency and retries: Braze may call your endpoint more than once per recipient. Ensure your endpoint can tolerate duplicate requests without incorrect side effects.

Authentication types

Using basic authentication

If the URL requires basic authentication, Braze can store a basic authentication credential for you to use in your API call. You can manage existing basic authentication credentials and add new ones at Settings > Connected Content.

To add a new credential, select Add credential > Basic authentication.

Give your credential a name and enter the username and password.

You can then use this basic authentication credential in your API calls by referencing the token’s name:

1
Hi there, here is some fun trivia for you!: {% connected_content https://yourwebsite.com/random/trivia :basic_auth credential_name %}

Using token authentication

When using Braze Connected Content, you may find that certain APIs require a token instead of a username and password. Braze can also store credentials that hold token authentication header values.

To add a credential that holds token values, select Add credential > Token authentication. Then, add the key-value pairs for your API call headers and the allowed domain.

You can then use this credential in your API calls by referencing the credential name:

1
2
3
4
5
6
7
8
9
{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://api.endpoint.com/your_path
     :method post
     :auth_credentials token_credential_abc
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

Using Open Authentication (OAuth)

Some API configurations require the retrieval of an access token that can then be used to authenticate the API endpoint that you want to access.

Step 1: Retrieve the access token

The following example illustrates retrieving and saving an access token to a local variable, which can then be used to authenticate the subsequent API call. A :cache_max_age parameter can be added to match the time that the access token is valid for and reduce the number of outbound Connected Content calls. See Configurable Caching for more information.

1
2
3
4
5
6
7
8
9
10
{% connected_content
     https://your_API_access_token_endpoint_here/
     :method post
     :auth_credentials access_token_credential_abc
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE"
     }
     :cache_max_age 900
     :save token_response
%}

Step 2: Authorize the API using the retrieved access token

After the token is saved, it can be dynamically templated into the subsequent Connected Content call to authorize the request:

1
2
3
4
5
6
7
8
9
{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
     }
     :body key1=value1&key2=value2
     :save response
%}

Editing credentials

You can edit the credential name for authentication types.

• For basic authentication, you can update the username and password. Note that the previously entered password will not be visible.
• For token authentication, you can update the header key-value pairs and the allowed domain. Note that the previously set header values will not be visible.

Connected Content IP allowlisting

When a message using Connected Content is sent from Braze, the Braze servers automatically make network requests to our customers’ or third parties’ servers to pull back data. With IP allowlisting, you can verify that Connected Content requests are actually coming from Braze, adding a layer of security.

Braze will send Connected Content requests from the following IP ranges. The listed ranges are automatically and dynamically added to any API keys that have been opted in for allowlisting.

Braze has a reserved set of IPs used for all services, not all of which are active at a given time. This is designed for Braze to send from a different data center or do maintenance, if necessary, without impacting customers. Braze may use one, a subset, or all of the following IPs listed when making Connected Content requests.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)

User-Agent header

Braze includes a User-Agent header in all Connected Content and webhook requests that is similar to the following:

1
Braze Sender 75e404755ae1270441f07eb238f0faf25e44dfdc

Troubleshooting

Use Webhook.site to troubleshoot your Connected Content calls.

1. Switch the URL in your Connected Content call with the unique URL generated on the site.
2. Preview and test your campaign or Canvas step to see the requests come through to this website.

Using this tool, you can diagnose issues with the request headers, request body, and other information that is being sent in the call.

Frequently asked questions

Why are there more Connected Content calls than users or sends?

This is expected behavior. Braze may make the same Connected Content API call more than once per recipient because message payloads can be rendered multiple times (for example, for email HTML, plain text, and AMP; for validation or retry logic; or other internal purposes). There is no guaranteed 1:1 ratio between sends and Connected Content calls. See Understanding Connected Content call volume and Best practices for high-volume endpoints for details and mitigation.

How does rate limiting work with Connected Content?

Connected Content doesn’t have its own rate limit. Instead, the rate limit is based on the message-sending rate. We recommend setting the messaging rate limit below your intended Connected Content rate limit if there are more Connected Content calls than messages sent.

What is caching behavior?

GET requests are cached by default (see Caching responses). POST requests are not cached by default, but you can enable caching by adding :cache_max_age to the Connected Content call. This can reduce endpoint load when the same POST (for example, a token or content request) would be made repeatedly within the cache window.

1
{% connected_content https://api.example.com/token :method post :body grant_type=client_credentials :cache_max_age 900 :save token %}

Caching can help reduce duplicate Connected Content calls but isn’t guaranteed to result in a single call per user. Cache duration is between five minutes and four hours. For full details, see Caching responses.

What is the Connected Content HTTP default behavior?

By default, Connected Content will set a Content-Type header on a GET HTTP request that it makes to application/json with Accept: */*. If you require another content type, specify it explicitly by adding :content_type your/content-type to the tag. Braze will then set both the Content-Type and Accept header to the type you specify.

1
{% connected_content http://numbersapi.com/random/trivia :content_type application/json %}

By default, Connected Content makes an HTTP GET request to the specified URL. To make a POST request instead, specify :method post.

You can optionally provide a POST body by specifying :body followed by either a query string of the format key1=value1&key2=value2&... or a reference to captured values. Content-Type defaults to application/x-www-form-urlencoded. If you specify :content_type application/json and provide a form-urlencoded body such as key1=value1&key2=value2, Braze will automatically JSON-encode the body before sending.

Connected Content also does not cache POST calls by default. You can update this behavior by adding :cache_max_age to the Connected Content POST call.

• default content-type
• application/json content-type

1
{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 %}

1
{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 :content_type application/json %}