The ActiveTrail API: Contacts, Campaigns and the Token Nobody Documents

ActiveTrail is an Israeli email marketing and SMS platform, and its REST API covers five areas: contacts, groups, campaigns, automations and SMS. The rule of thumb it presents is that anything you can do in the interface you can do through the API - broadly accurate, with several operational details worth knowing up front.

The first confusing thing: the domain

The documentation and the API host sit on webapi.mymarketing.co.il - not on activetrail.com.

That sounds trivial and has two practical consequences:

• Searching "ActiveTrail API docs" does not necessarily lead there. Save the address.
• In a firewall allowlist or a security review, a domain that does not carry the product's name looks suspicious. Whoever reviews the configuration in a year will ask what it is - document it.

Worth knowing too that ActiveTrail does not publish an official OpenAPI specification. What exists is readable documentation and community-maintained specs - meaning you will not get an auto-generated client and will write the access layer yourself. That is hours of work rather than days, but it belongs in the estimate.

Authentication - and the details that break it later

Authentication is an API token in an authorization header, generated in the interface under settings and then API apps.

And there are two options there that change everything:

The token can expire

You can set it an expiry date. That is good security, and it is also how an integration stops working without anyone knowing.

The scenario: everything worked for six months, and then website leads stopped reaching the mailing list. No crash, no alert - just silence. Whoever debugs it six months later will not suspect the token, because they will not know an expiry was set.

The token can be IP-locked

You can restrict it to specific addresses. Excellent for security, and a problem when something moves: a server migration, an infrastructure change, a deploy to a new environment - all of which look like "the integration broke" rather than "the IP changed".

What to do in both cases:

• Document whether an expiry was set and when, and whether there is an IP restriction and for which addresses - somewhere whoever maintains it will look, not in a code comment.
• Alert before the expiry, not after.
• Handle an authentication error explicitly rather than swallowing it. An integration writing to a mailing list should shout when it is rejected, not fail quietly.

Creating a campaign does not send it

This is the important design point: creating a campaign and sending it are two separate operations. You create a campaign, and then there is an explicit call that triggers the send.

It is easy to treat that as a nuisance. It is in fact a safety feature, and one worth using.

Email differs from most API operations: it is irreversible. There is no undo after sending to ten thousand people. Separating the steps gives you a window to verify - that the group is right, the content is right, the recipient count is plausible.

The pattern I recommend: create automatically, send by a conscious decision. If your system builds campaigns automatically, have someone approve the send - or at minimum a check that halts if the recipient count exceeds what was expected. A faulty script that creates a draft is an incident; a faulty script that sends is reputational damage.

Contacts and groups - the matching that is all the work

In most projects what actually happens is a sync: leads from the website or the CRM entering a mailing list.

And the same question recurs: does this person already exist?

• Normalise before comparing. Email - lowercase and trimmed. Phone - to E.164, because 052-1234567 and +972521234567 are the same person and will not look like it as strings.
• Update rather than create on a match. Otherwise duplicates accumulate and produce duplicate mailings - which is not merely a technical problem, it is a reason people click unsubscribe.
• Idempotency. A form submitted twice does not create two subscribers.

What must travel with the lead

Not just email and name. The lead source - which campaign or page it came from - is what makes later segmentation possible. If you did not pass it at signup, it is gone; it cannot be reconstructed retroactively.

SMS from the same API

The API also covers SMS. That is convenient, and there is one point worth pausing on.

One token controls two channels. If it leaks, whoever holds it can send email and SMS to your entire list. SMS also carries a direct per-message cost - meaning a leak has an immediate financial price, not only a reputational one.

So: server-side token only. Not in source control, not in logs, not in anything running in a browser. And on any suspicion of a leak, rotate immediately in the interface rather than monitoring for misuse.

What must be in place

• Email and phone normalisation on both sides before comparing.
• Idempotency on signups.
• An error queue a human sees. A lead that failed to write to the list is a lead who will receive nothing.
• Separation of create and send - with a recipient-count check before any automated send.
• Token expiry monitoring if an expiry was set.

Checklist

1. Save the documentation address - it is not on the domain you expect.
2. Establish whether the token has an expiry and an IP lock, and document it.
3. Set an alert before the expiry.
4. Confirm create and send are separated, with approval or a scope check before sending.
5. Normalise email and phone before every comparison.
6. Pass the lead source at signup - there is no way back.
7. Confirm the token appears in no client-side code.