Filtering by API results

The API filter allows you to run campaigns based on data obtained from an external endpoint—for example, information about weather, geolocation, device type, traffic in the area, etc. Before evaluating a campaign, Mailocator loads the JSON response from the API you specified and decides whether to display the campaign based on the values it contains.

This gives you the ability to use any external data that is not available in standard filters and tailor the campaign display to the current situation.

Setting up an endpoint in Mailocator

First, you need to connect the API endpoint in Mailocator Settings.

Open Mailocator Settings and go to External API Connection

Add the URL of your endpoint (e.g., weather service, geolocation, etc.)

Authentication
Currently, no authorization at the HTTP header level (Basic Auth, Bearer token, etc.) is supported.
However, it is possible to send the API key as a GET parameter in the URL, for example:
https://api.example.com/weather?city=Prague&api_key=XYZ123

Response format – JSON only
The endpoint must return data in JSON format.
Other formats (HTML, XML, text) are not supported. A typical example is:

{
  "city": "Prague",
  "temp": 5,
  "weather": "snow",
  "country": "CZ"
} 

Setting up a filter in a campaign

Once you have set up the endpoint, you can work with the data in filters:

Select a filter by API in the campaign.

Add any number of conditions based on the names of the values returned by the API (e.g., weather, temp, country, segment).

You can filter by equality, range, or specific values (e.g. weather = snow, temp = 0, country = CZ).

When loading a page, Mailocator calls the specified API endpoint, loads JSON data, and evaluates whether the filter conditions apply. If so, the campaign can be displayed.

Best practice

Filtering by API is particularly useful when you need strong external context:

Weather – offering winter clothing, hot drinks, or heating when temperatures are low, or summer campaigns when it's hot.

Geolocation / region – local events, availability of services only in a specific city or zone.

Special statuses – e.g., the API returns the status of your system, product availability, "happy hours," or a special promo window.