The API
Everything the Linktrail web app does, you can do from your own programs — the app is a client of the same API described below.
Getting started
Every endpoint below is under one base URL:
https://app.aurelia.lt/api/v1
Authenticate with an API key, created from the “API & agents” page of the app once you are signed in. Send it as a bearer token on every request:
Authorization: Bearer trk_live_YOUR_API_KEY
A request with no key, or a revoked one, is refused before anything else runs. Every response — success or failure — is JSON. An error looks like this, always with a stable, machine-readable code:
{ "error": { "code": "not_found", "message": "contact not found" } }| Status | Code | Means |
|---|---|---|
| 400 | invalid_request | A required field is missing or malformed. |
| 400 | invalid_json | The request body is not valid JSON. |
| 401 | missing_api_key | No Authorization header was sent. |
| 401 | invalid_api_key | The key is wrong or has been revoked. |
| 401 | account_suspended | The key is valid but the account is not active. |
| 402 | plan_limit | Creating this would pass a limit of your plan. The error carries limit, plan, allowed and used. See “Plans, limits and billing”. Only creating is ever refused; tracking never is. |
| 403 | email_not_confirmed | Confirm your email address before creating anything. |
| 404 | not_found | Nothing with that id, or it belongs to another account — the two are indistinguishable on purpose. |
| 409 | slug_taken, slug_mismatch, sent_at_already_recorded | The thing you asked for conflicts with what exists: a link name already held, the same external_ref with a different name, or a send time that is already recorded and cannot change. Details under Links and Messages. |
| 413 | payload_too_large | The request body was over 1 MB. |
| 422 | slug_not_allowed | The link name is a reserved or brand word. See “Choose the link's name”. |
| 429 | rate_limited | Too many requests. The response carries a Retry-After header, in seconds. |
| 429 | link_rate_limited | A new free account may create 100 links in any 24 hours during its first 7 days. The error carries limit, window_hours and used. Paid plans have no such limit. |
Rate limit: 300 requests per minute per key, by default. Bulk endpoints below accept up to 500 rows in one call.
Contacts
A contact is one tracked person. Every message, link and page view eventually points back to one — or to nobody, for a link shared publicly rather than sent to a named person (see Links below).
Create or find a contact
curl -X POST https://app.aurelia.lt/api/v1/contacts \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"external_ref": "user-42", "label": "Jane Doe"}'POST /api/v1/contacts →
{ "id": 1, "external_ref": "user-42" }external_ref is optional — omit it and one is generated for you. Calling this again with the same external_ref returns the same contact rather than creating a second one. label and meta (any JSON object of your own) are both optional.
Create many at once
curl -X POST https://app.aurelia.lt/api/v1/contacts/bulk \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contacts": [{"external_ref": "user-42"}, {"external_ref": "user-43"}]}'POST /api/v1/contacts/bulk → up to 500 rows, never all-or-nothing:
{
"results": [
{ "ok": true, "id": 1, "external_ref": "user-42" },
{ "ok": true, "id": 2, "external_ref": "user-43" }
]
}One malformed row fails only that row — every entry carries ok, and a failed one carries error: { code, message } instead of the created fields.
Look one up
curl "https://app.aurelia.lt/api/v1/contacts?external_ref=user-42" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/contacts?external_ref= — an exact match, never a search:
{
"id": 1,
"external_ref": "user-42",
"label": "Jane Doe",
"meta": null,
"opens": 14,
"clicks": 6,
"pageViews": 9,
"firstSeenAt": "2026-09-01T09:03:11.000Z",
"lastSeenAt": "2026-09-10T14:22:05.000Z",
"trackingOptedOutAt": null
}Search by the start of a reference
curl "https://app.aurelia.lt/api/v1/contacts?q=user-4&limit=20" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/contacts?q= — contacts of your account whose external_ref starts with the text (as typed, or in lowercase), newest activity first, at most limit of them (default 50, largest 200), in the same { items, next_cursor } shape as the list, where next_cursor is always null. The text is 1 to 200 characters. It cannot be combined with external_ref or cursor (that is a 400 invalid_request). Without q and without external_ref, the same path lists your contacts, newest activity first, with ?cursor=&limit=.
The journey
The whole story for one person, oldest first — opens, clicks and page views, in order.
curl "https://app.aurelia.lt/api/v1/contacts/1/journey?limit=50" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/contacts/:id/journey →
{
"items": [
{
"source": "event",
"ts": "2026-09-10T09:04:00.000Z",
"kind": "email_open",
"subject": { "type": "message", "id": 9, "external_ref": "welcome-email" }
},
{
"source": "event",
"ts": "2026-09-10T09:06:12.000Z",
"kind": "link_click",
"subject": { "type": "link", "id": 4, "external_ref": "pricing-link" }
},
{
"source": "page_activity",
"ts": "2026-09-10T09:06:15.000Z",
"kind": "page_view",
"subject": { "type": "site", "id": 2, "external_ref": "example.com" },
"page": {
"path": "/pricing",
"started_at": "2026-09-10T09:06:15.000Z",
"ended_at": "2026-09-10T09:07:16.000Z",
"active_ms": 42000,
"total_ms": 61000,
"max_scroll_pct": 88
}
}
],
"next_cursor": "eyJ0cyI6IjIwMjYtMDktMTAifQ=="
}kind is one of email_open, link_click, page_view or session_start. next_cursor is present only when there may be more — pass it back as ?cursor= for the next page.
Erase a contact
curl -X DELETE https://app.aurelia.lt/api/v1/contacts/1 \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
DELETE /api/v1/contacts/:id →
{ "id": 1, "erased": true }This genuinely erases — every open, click and page view this person generated is gone, not hidden. It cannot be undone.
Messages
A message is one tracked email. Creating one returns a pixel_url — embed it once, near the top of the email you send, as <img src="pixel_url" width="1" height="1" alt="">.
Create a message
curl -X POST https://app.aurelia.lt/api/v1/messages \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contact_id": 1, "external_ref": "welcome-email"}'POST /api/v1/messages →
{
"id": 9,
"external_ref": "welcome-email",
"label": null,
"pixel_url": "https://t.aurelia.lt/p/Q7mZ3xVnR9pLk2WbT6cAeg"
}Create many at once
POST /api/v1/messages/bulk — the shape a campaign sender uses. Up to 500 rows, same per-row { ok, ... } contract as Contacts above, each successful row carrying the same fields POST /api/v1/messages returns.
List messages
curl "https://app.aurelia.lt/api/v1/messages?limit=20" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/messages?cursor=&limit= → newest first; next_cursor is null on the last page:
{
"items": [
{
"id": 9,
"external_ref": "welcome-email",
"label": null,
"sent_at": "2026-09-10T09:00:00.000Z",
"opens": 14,
"opens_human": 3,
"opens_machine": 10,
"first_open_at": "2026-09-10T09:04:00.000Z",
"last_open_at": "2026-09-11T08:12:00.000Z",
"person": { "id": 1, "external_ref": "user-42", "label": "Jane Doe" }
}
],
"next_cursor": null
}opens_machine counts the opens judged proxy_open, prefetch or scanner, each counted directly; it is never opens minus opens_human, because that would fold unknown into it. person is the contact the message was made for.
Read a message's stats
curl https://app.aurelia.lt/api/v1/messages/9 \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/messages/:id →
{
"id": 9,
"external_ref": "welcome-email",
"label": null,
"pixel_url": "https://t.aurelia.lt/p/Q7mZ3xVnR9pLk2WbT6cAeg",
"sent_at": "2026-09-10T09:00:00.000Z",
"opens": 14,
"opens_human": 12,
"opens_human_via_gmail": 9,
"verdicts": { "human": 12, "proxy_open": 0, "prefetch": 0, "scanner": 1, "unknown": 1 },
"first_open_at": "2026-09-10T09:04:00.000Z",
"last_open_at": "2026-09-11T08:12:00.000Z",
"drops": {
"total": 0,
"note": "events dropped for this account since the process last started — opens is a floor, not exact"
},
"person": { "id": 1, "external_ref": "user-42", "label": "Jane Doe" },
"opens_timeline": {
"items": [
{ "ts": "2026-09-11T08:12:00.000Z", "verdict": "human", "device": "iPhone", "network": null,
"connection": "home_or_mobile", "connection_provider": null, "reader": "r2", "seconds_after_send": 83520, "via": null },
{ "ts": "2026-09-10T09:04:00.000Z", "verdict": "human", "device": null, "network": "google",
"connection": "mail_proxy", "connection_provider": "google", "reader": null, "seconds_after_send": 240, "via": "gmail" }
],
"total": 14,
"truncated": true
},
"distinct_readers": 4,
"distinct_readers_human": 2,
"distinct_clickers": 1,
"distinct_readers_by_connection": { "data_centre": 1, "home_or_mobile": 2, "mail_proxy": 0, "scanner": 1, "unknown": 0 },
"distinct_readers_capped": false,
"distinct_readers_upper_bound": false,
"first_human_open_at": "2026-09-10T09:40:00.000Z",
"seconds_to_first_open": 240,
"seconds_to_first_human_open": 2400,
"opens_by_connection": { "data_centre": 1, "home_or_mobile": 3, "mail_proxy": 9, "scanner": 1, "unknown": 0, "not_recorded": 0 },
"opens_without_reader": 9,
"clicks_timeline": {
"items": [
{ "link_id": 4, "ts": "2026-09-10T09:06:12.000Z", "verdict": "human", "connection": "home_or_mobile",
"connection_provider": null, "reader": "r2", "seconds_after_send": 372 }
],
"total": 1,
"truncated": false
},
"definitions": { "connection": "what kind of connection ...", "reader": "r1, r2, ...", "distinct_readers": "..." }
}Read opens and opens_human together, never one alone — see “Understanding the numbers” below. opens_timeline holds the newest 100 opens, newest first, with total the number of opens and truncated true when older ones are not shown. A device is a short word such as iPhone, Windows or Mac (approximate: it comes from the browser's own description), and is null for a machine verdict, because a mail provider's proxy names a device that is not the reader's. network is the name of a recognised provider or null. No address of any kind is returned.
Connection kinds and readers
Every open and click is sorted by connection kind from the address it came from, at the moment it arrives, using an offline list that never sends the address anywhere. The address itself is never returned, and nothing returned is computed from it except the fields below. Each field is also explained in the definitions object of the response. The four per-item fields appear on every item of opens_timeline and clicks_timeline and on every open and click in GET /api/v1/events; a page view returns them as null.
connection— one of five kinds, ornullfor an event recorded before sorting existed.data_centre: on a bundled list of data-centre, hosting, VPN, or CDN and relay exit ranges. It includes VPNs and CDN or relay exits, so most Apple Mail Privacy Protection opens land here (Apple's private-relay list is not bundled).home_or_mobile: not on any bundled data-centre, VPN, mail-proxy or scanner list — usually a home, mobile or office connection; an inference, not a lookup.mail_proxy: a mail provider's image proxy fetched it, not the reader's own device.scanner: a security scanner's network fetched it.unknown: no address, or one that cannot be a public internet client.connection_provider—google,appleormicrosoft, only when the connection ismail_proxy; otherwisenull.reader—r1,r2, ...: a number assigned per email, in order of first appearance, to each address-and-device-type pair, and never computed from the address. The same string means the same address and device type within one email only;r1of one email says nothing aboutr1of another. For a click, the email is the one the clicked link belongs to.nullmeans no label: amail_proxyconnection (Gmail's image proxy and any other mail proxy on our list; every reader behind one shares the provider's addresses) or an unknown one, an event with no email, an email already at its reader limit, or an event recorded before labels existed. Apple Mail Privacy Protection opens usually show asdata_centreand do get labels; Apple's relay addresses rotate, so one Apple reader can appear as several labels.seconds_after_send— whole seconds from the email'ssent_atto this event, truncated toward zero;nullwhensent_atis not recorded. It can be negative whensent_atwas recorded after the event arrived.
On the message itself:
distinct_readers,distinct_readers_human(labels with at least one open or click that looked like a person),distinct_clickers(labels with at least one click) anddistinct_readers_by_connection(labels grouped by the connection of the reader's first event). A label is an address-and-device-type pair, not a person. The count can be too high (one person on two devices or networks; Apple Mail Privacy Protection opens, whose relay addresses rotate) or too low (two people behind one shared address and device type count once; an email at its reader limit). Gmail's image proxy and other mail-proxy opens get no label and are not counted. To see how many labels look like people, readdistinct_readers_human, anddistinct_readers_by_connectionfor how many aredata_centre, where most Apple opens land.distinct_readers_cappedis true when the email reached the per-email reader limit (100 by default), so further readers get no label and the count is a floor.distinct_readers_upper_boundis true when the time from the first to the last labelled event is longer than your current IP retention setting (60 days by default): addresses are deleted after that, a returning reader cannot be matched to their old label and gets a new one, so the count can then be too high. It compares against the current setting only, so labels split under an earlier, shorter setting (for example, if this account's setting was lowered and later raised) can be too high while it is false; a false flag never means the count is exact.first_human_open_at,seconds_to_first_openandseconds_to_first_human_open: times fromsent_at,nullwhen not known and negative whensent_atwas recorded late.opens_by_connection— the connection kinds plusnot_recorded(opens with no stored kind: recorded before sorting existed, or no longer stored), so the values always sum toopens.opens_without_readercounts stored opens that have no label.clicks_timelineholds the newest 100 clicks on the email's links, withtotalandtruncatedlikeopens_timeline.
Record when it was sent
curl -X POST https://app.aurelia.lt/api/v1/messages/9/sent \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sent_at": "2026-09-10T09:00:00.000Z"}'POST /api/v1/messages/:id/sent →
{ "id": 9, "sent_at": "2026-09-10T09:00:00.000Z", "reclassified": 14 }An open that arrives before the send time is known is still recorded, but cannot yet be judged — it shows as unknown until you call this, even after the fact, at which point every open already collected is re-judged. Omit sent_at and it defaults to now. The first send time recorded stays: sending a different one later is 409 sent_at_already_recorded, because every open is judged by its distance from the send time. Sending the same value again is harmless.
Links
A link records a click, then sends the person straight on — instantly, never through an interstitial page. contact_id is optional: give one for a link sent to a named person, or leave it out (or send it as null) for an open link shared publicly, whose clicks belong to nobody in particular.
Create a link
curl -X POST https://app.aurelia.lt/api/v1/links \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contact_id": 1, "target_url": "https://example.com/pricing"}'POST /api/v1/links →
{
"id": 4,
"external_ref": "l-4",
"contact_id": 1,
"url": "https://t.aurelia.lt/l/aB3dE9fG7hK",
"custom_slug": false
}Send url, never the original address — it redirects straight to target_url on click. Every link response also carries custom_slug: true for a name you chose, false for a random one. The host in url is the one your account tracks on (the shared tracking domain, or your own once it is working).
Creating can be refused with 402 plan_limit (a limit of your plan, for example the number of custom link names) or, for a new free account, 429 link_rate_limited. A repeat of an existing external_ref is not a new link and is never counted.
Create many at once
POST /api/v1/links/bulk — up to 500 rows, the same { ok, ... } contract as Contacts and Messages above. Each row may carry its own slug; a name that is taken or not allowed fails that row only.
Choose the link's name
Add slug to a create and the link ends in your word instead of a random one:
curl -X POST https://app.aurelia.lt/api/v1/links \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contact_id": 1, "target_url": "https://example.com/pricing", "slug": "acme-pricing"}'{
"id": 5,
"external_ref": "l-5",
"contact_id": 1,
"url": "https://t.aurelia.lt/l/acme-pricing",
"custom_slug": true
}- Lowercase letters
a-z, digits0-9and single hyphens between them. ASCII only, 4 to 40 characters. Capitals are lowercased, and the name is matched ignoring case. A name of exactly 11 letters and digits with no hyphen is reserved for random links and refused with422 slug_not_allowed. - One name belongs to one link across all accounts, first come first served. Taken:
409 slug_takenwith asuggestionto send instead. Brand, login and reserved words:422 slug_not_allowed. Anything else wrong with the name:400 invalid_slug(accents are refused, with the accent-free word as the suggestion). - A name never changes and is never reused, even after its link is erased. The same
external_refwith the same name returns the same link; with a different name it is409 slug_mismatch. - A custom link can be guessed. Never use one for a private page. A random link is a secret; a name is not.
Is this name free?
curl "https://app.aurelia.lt/api/v1/links/slug-availability?slug=acme-pricing" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/links/slug-availability?slug= → asks without creating anything (needs a confirmed email address):
{ "available": false, "reason": "taken", "message": "that word is already taken", "suggestion": "acme-pricing-2" }reason is available, taken, invalid or not_allowed. It never says who holds a name, and a name that was held by an erased link answers taken too. The answer is true only for the moment it is given.
List links
GET /api/v1/links?cursor=&limit= → newest first, each row with id, external_ref, contact_id, url, custom_slug, target_url, created_at, clicks, clicks_human and last_click_at; next_cursor is null on the last page.
Read a link's stats
curl https://app.aurelia.lt/api/v1/links/4 \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/links/:id →
{
"id": 4,
"external_ref": "l-4",
"contact_id": 1,
"url": "https://t.aurelia.lt/l/aB3dE9fG7hK",
"custom_slug": false,
"target_url": "https://example.com/pricing",
"site_id": null,
"clicks": 6,
"clicks_human": 5,
"verdicts": { "human": 5, "proxy_open": 0, "prefetch": 0, "scanner": 1, "unknown": 0 },
"first_click_at": "2026-09-10T09:06:12.000Z",
"last_click_at": "2026-09-12T11:00:00.000Z",
"distinct_clickers_30d": 4,
"country_breakdown": { "by_country": { "US": 4, "DE": 1 } },
"drops": {
"total": 0,
"note": "events dropped for this account since the process last started — clicks is a floor, not exact"
}
}distinct_clickers_30d counts distinct browsers or devices, over the last 30 days, that completed the identity hop after a click — never raw IP addresses. It is not a headcount, and it is not a bound in either direction: one person on a phone and a laptop is two browsers, so it can read higher than the number of people — and two people sharing one machine are one browser, so it can read lower. The field name says “clickers” and that is the wrong word — it is kept because changing a published API field breaks whoever reads it, and this page is where it is explained. The window is in the field's own name on purpose; see “Understanding the numbers” for the verdict breakdown, which works identically for clicks and opens.
Sites
Register a site once, then add one line of JavaScript to it to record which pages a person reads and how long they spend.
Register a site
curl -X POST https://app.aurelia.lt/api/v1/sites \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com"}'POST /api/v1/sites →
{
"id": 2,
"domain": "example.com",
"site_key": "kQ2m9F3pXzT8waLj4dY6Rt",
"tracking_mode": "basic",
"snippet": "<script async src=\"https://t.aurelia.lt/s.js?k=kQ2m9F3pXzT8waLj4dY6Rt\"></script>"
}Registering the same domain again is safe — it returns the same site rather than creating a second one. Every site response carries snippet, the ready-to-paste tag. It uses your own tracking domain once that is working.
Read a site
curl https://app.aurelia.lt/api/v1/sites/2 \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/sites/:id → the same shape as above.
Change the tracking mode
curl -X POST https://app.aurelia.lt/api/v1/sites/2/tracking-mode \
-H "Authorization: Bearer trk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tracking_mode": "extended"}'POST /api/v1/sites/:id/tracking-mode — basic or extended:
{
"id": 2,
"domain": "example.com",
"site_key": "kQ2m9F3pXzT8waLj4dY6Rt",
"tracking_mode": "extended",
"snippet": "<script async src=\"https://t.aurelia.lt/s.js?k=kQ2m9F3pXzT8waLj4dY6Rt\"></script>"
}Basic records only people who arrived through one of your tracked links. Extended also records people who simply visit the site, and retroactively attaches their browsing to their contact record if they click a tracked link within 30 days. A mode change takes up to an hour to reach an already-cached visitor.
Add the snippet to your site
<script src="https://t.aurelia.lt/s.js?k=kQ2m9F3pXzT8waLj4dY6Rt" async></script>
If you set your own tracking domain, your snippet uses that instead — copy it from the Websites page.
One line, anywhere on the page. Nothing else to configure — the tracking mode set above travels with it, and a mode change reaches this script the same way any other cached response does.
Events
One feed across every layer — opens, clicks and page views — for a poller to consume instead of pulling each resource on a timer.
curl "https://app.aurelia.lt/api/v1/events?cursor=0&limit=200" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/events?cursor=&since=&limit= →
{
"items": [
{
"id": 101,
"contact_id": 1,
"kind": "link_click",
"ts": "2026-09-10T09:06:12.000Z",
"verdict": "human",
"classifier_version": "3",
"subject": { "type": "link", "id": 4, "external_ref": "l-4" },
"connection": "home_or_mobile",
"connection_provider": null,
"reader": "r2",
"seconds_after_send": 372
}
],
"next_cursor": "101",
"definitions": { "connection": "...", "connection_provider": "...", "reader": "...", "seconds_after_send": "..." }
}next_cursor is an opaque, always-increasing id — store it and pass it back as ?cursor= on the next poll. It is not a timestamp and must not be treated as one: events can insert slightly out of time order, so polling by time can permanently miss a row. ?since= is a convenience filter only, never a substitute for the cursor. contact_id is null for an open link's clicks, which belong to nobody in particular. Each open and click also carries connection, connection_provider, reader and seconds_after_send — see “Connection kinds and readers” under Messages; a page view returns all four as null. The response's definitions object says what each one counts.
Overview
The account's totals over a window, the same figures the Overview screen draws. Every count is returned with what it counts, and every open and click carries the full verdict breakdown by name.
curl "https://app.aurelia.lt/api/v1/overview?days=30" \ -H "Authorization: Bearer trk_live_YOUR_API_KEY"
GET /api/v1/overview?days=&link_id= — both optional. days is 7, 30 or 90: a whole number is rounded up to the next of those (8 gives 30, anything above 30 gives 90), and a missing or malformed value gives 30, never an error. The response says which window it used, as window_days. Answers are cached for a minute per account, window and link, so a click you make this second may not show for up to a minute.
{
"window_days": 30,
"opens": 120, "opens_human": 31, "opens_verdicts": { "human": 31, "proxy_open": 70, "prefetch": 2, "scanner": 9, "unknown": 8 },
"clicks": 44, "clicks_human": 29, "clicks_verdicts": { "human": 29, "proxy_open": 0, "prefetch": 1, "scanner": 12, "unknown": 2 },
"page_views": 63,
"people_active": 17,
"daily": [ { "day": "2026-09-10", "opens_people": 3, "opens_other": 9, "clicks_people": 2, "clicks_other": 1, "page_views": 4, "people_active": 3 } ],
"previous": { "starts_on": "2026-08-11", "ends_on": "2026-09-10", "opens": 98, "opens_human": 22, "clicks": 31, "clicks_human": 20, "page_views": 40, "people_active": 12 },
"top_links": [ { "id": 4, "external_ref": "l-4", "target_host": "example.com", "clicks_people": 11, "clicks_all": 15 } ],
"countries": [ { "country": "DE", "clicks_people": 7 } ],
"countries_other": 3,
"devices": [ { "device": "iPhone", "count": 14 } ]
}Illustrative figures; the field names are the real ones (the list above also carries events_per_day, one { day, count } per day, and the previous object has the same totals). previous is the window of the same length just before this one, cut at the same time of day so the comparison is like with like. Countries come from clicks only, because an open's address is often a mail provider's proxy, and no address is ever returned. people_active counts different contacts with a person-like open or click, or a page view, in the window.
With link_id the same kind of answer is about that one link: clicks, clicks_human, clicks_verdicts, browsers (distinct browsers, not people), daily, previous, countries, devices and who_clicked. A link that is not yours is 404 not_found, and a link_id that is not a positive whole number is 400 invalid_request.
Plans, limits and billing
GET /api/v1/plans needs no key. It lists the public plans with their prices (in euro, excluding VAT, prices_exclude_vat says so) and limits, from the same file the pricing page is built from: events_per_month, sites, custom_words, custom_domains, and for the partner plan the clients included and the most allowed. A limit of null means no limit. It may be cached for five minutes.
Two further reads take your key: GET /api/v1/account (your own record) and GET /api/v1/usage?month=YYYY-MM (stored events for one UTC month, the current one by default).
What a limit does
- A limit is checked only when you create something: a link, a message, a site, a custom link name, a custom tracking domain, or a client account. Over it, the call answers
402 plan_limitwith{ limit, plan, allowed, used }, wherelimitnames which one:events_per_month,sites,custom_words,custom_domainsorchildren. - Nothing already sent ever stops working, and no event is ever dropped for a plan reason. Pixels, links and the snippet keep recording whatever your count is.
- Only the free plan is refused for passing its monthly events (new links, messages and sites wait until next month or an upgrade). Paid plans get an email at 80 % and again at 100 % and are never refused for events.
Paying
The billing calls move money, so they take a signed-in browser session and never an API key (a key gets 403 api_key_not_allowed). Use the Billing screen, or: GET /api/v1/billing (plan, status, usage against the limit, every limit with its current count), POST /api/v1/billing/checkout with { "plan": "starter", "interval": "monthly" }, which answers { "url": ... }, a Stripe-hosted payment page (card details never reach us), and POST /api/v1/billing/portal, which answers the address of Stripe's page for changing a card or cancelling. An account that already subscribes is sent to the portal instead (409 already_subscribed). A client account of a partner is billed through its partner.
Understanding the numbers
Every open and every click is judged, and the judgement is returned by name — never folded into a single yes/no. There is no chart or count anywhere in this product with only two buckets, “human” and “not human”, because that would hide which of four different things “not human” actually was.
| Verdict | On screen | What produces it |
|---|---|---|
| human | looks like a person | Nothing flagged it as a scanner or a mail service that downloaded the image automatically, or it came through the Gmail image proxy, which fetches when a person opens the email (opens_human_via_gmail counts those, and the via field of an open says which). That is not proof of a person: automated opens we cannot recognise, Apple Mail Privacy Protection above all, can still land here, so read it as "at most this many people", never "exactly". |
| proxy_open | Apple or another mail service fetched it automatically for the reader | The fetch came from a mail-provider proxy network we recognise, such as Apple's. The Gmail image proxy is not here: it counts as a person (human, via gmail). |
| prefetch | a browser or mail app fetched it ahead of time | A prefetch header was present. |
| scanner | a company's security scanner checked it | A HEAD request, a known scanner network, a known automation program (curl, a headless browser and similar), browser navigation headers that were present and wrong, or an open of an email within 30 seconds of its recorded send time from something that looks like a desktop browser or sends no user-agent. Mail apps and phones are never judged a scanner by timing alone. For a link click: a click within 3 seconds of send that does not look like a browser navigation. |
| unknown | not enough information to say | Usually: no send time recorded yet. Also an open from a very old desktop browser version with nothing else to go on. |
opens is every fetch of the pixel; opens_human counts only the fetches judged human — and it counts events, not people: the same person opening twice counts twice. The gap between the two is never computed by subtraction — each of the other four verdicts is counted and returned by name under verdicts, so nothing is hidden inside “the rest”. The same five words, and the same rule, apply to link clicks: clicks and clicks_human.
Even human is a judgement, not a finding. It means nothing we could recognise marked the fetch as a machine. Apple Mail Privacy Protection fetches the images of many readers' mail in advance, and not every address it uses is known to us, so some of those fetches are counted here. Read opens_human as “at most this many person-opens”. The rules were tightened on 2026-10-07 and apply to opens recorded from then on; older opens keep the verdict they were given, except that recording a send time re-judges that message's opens under today's rules.
A proxy_open — an email service fetching the image automatically — is not a person reading your email, but it usually means the email was delivered. For a reader whose provider proxies images this way, later opens by the same person often never reach this product at all, once the provider's own cache already holds the image — so opens under-counts for those readers rather than over-counting. This is the one place these numbers are too low rather than too high, and it is worth saying plainly: it is what makes the rest of them credible.
unknown — not enough information to say — usually means no send time has been recorded yet. See POST /api/v1/messages/:id/sent above.
Opting someone out
Called from an unsubscribe or opt-out page you control — not from your backend, and not with an API key. It takes the visitor token carried by a tracked link or the site snippet.
curl -X POST https://t.aurelia.lt/optout \
-H "Content-Type: application/json" \
-d '{"token": "the visitor token from a tracked link or the snippet"}'POST /optout →
{ "ok": true }Always the same response, whether or not the token matched anything — so this endpoint can never be used to check whether a token is valid. It stops tracking for that person from that point on. It does not erase what has already been recorded; for that, erase the contact (see Contacts above).