Ad Serving API


Welcome to the Integrations section of our Ad Serving API documentation. As the digital advertising landscape evolves, seamless integration capabilities become paramount. Here, we provide comprehensive guides and resources to ensure smooth integration of our API with various platforms and tools. Whether you're looking to enhance your current systems or explore new advertising avenues, our detailed documentation will assist you every step of the way. Dive in to discover how our API can be harmoniously integrated to optimize your ad serving processes.

If you would like to do an official integration with us, please reach out.

Want to seamlessly insert native ads into your newsletters? Buttondown makes it easy to do so. All you have to do is provide Buttondown with your ad serving api endpoint, add the conditional inclusion of the ad in your template, and you are off to the races. Here's how:

  • Go to the "Templates" section and add your desired ad layout into the template:
{% load md %}
{% for ad in %} 
{% if ad.statlink %} 
## Sponsor 

{{ ad.description|md:newsletter|safe }}

[{{ad.callToAction }}]({{ ad.longlink }})
![]({{ ad.longimp }}) 
{% endif %} 
{% endfor %}

Some notes:

  • The for loop requires you utilize the zone key that you wish to pull the ads from. This is important, because it is possible to batch requests for multiple zones at once if you have multiple ad sections within your newsletter. (e.g. you modify the endpoint URL to include a second zone key like this:;CVADC53U.json?ignore=yes)

  • If you have markdown content in any of the fields returned by our API, you need to let Buttondown know that you intend for them to recognize markdown (e.g. ad.description|md:newsletter|safe)

  • In order to properly track opens, you shoud utilize the longimp. This is the image you see that references{{ ad.longimp }}.

  • For the link click, you should utilize longlink. As such, it is not passed through as a fully qualified URL, and you will need to construct it as shown in the template above:{{ ad.longlink }}

  • This is not a per-email-sent integration. It will pull an ad once at runtime when sending out emails and display the same ad fetched for each zone for all subscribers.

Here is a sample of what the template above will produce: