Tracking keys

Manage the public keys that the tracking script uses to send events from your website.

Base URLhttps://api.emailit.com/v2Authentication Errors Rate limits

POST/tracking-keys
GET/tracking-keys/{id}
POST/tracking-keys/{id}
GET/tracking-keys
DEL/tracking-keys/{id}

Create a tracking key

Creates a tracking key for the tracking script. The response includes the public key that goes into the script URL. Requires an API key with the full scope.

Tracking keys are public, so anyone can copy one from your page. They can only send workspace and custom events, never read data, and you can limit them to your own sites with allowed_origins. A workspace can have up to 25 tracking keys.

Website tracking is included with Pro, Business and Custom plans. Keys stay after a move to Pay as you go, but the tracking script’s requests with them return 403.

POST/tracking-keys

Body parameters

namestringdefault: Website

Name that tells you where the key is used, such as Online shop, up to 100 characters.

allowed_originsstring[]

The sites allowed to send events with the key, up to 50. Empty or omitted means any site. Each entry is one of:

an origin, such as https://shop.example.com: that scheme, host and port only;
a host, such as shop.example.com: that host on any scheme or port;
a wildcard, such as *.example.com: example.com and all of its subdomains.

Entries are stored in lowercase, without a trailing slash. A string with entries separated by spaces or commas is accepted too.

enabledbooleandefault: true

false creates the key turned off.

Returns

Returns 201 Created with the tracking key object.

Status	When
`403`	The API key doesn’t have the `full` scope, or the workspace is on Pay as you go: `error` is `plan_required` and `required_plan` is `pro`.
`422`	A field is invalid, for example an entry in `allowed_origins` that isn’t an origin, host or wildcard. `errors` is keyed by field and `message` repeats the first problem. Also returned with `code: "tracking_keys_limit"` when the workspace already has 25 tracking keys.

POST/tracking-keys

Terminal

curl -X POST https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Online shop",
    "allowed_origins": ["https://shop.example.com", "*.example.com"]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/tracking-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Online shop',
    allowed_origins: ['https://shop.example.com', '*.example.com'],
  }),
});
const trackingKey = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/tracking-keys",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "name": "Online shop",
        "allowed_origins": ["https://shop.example.com", "*.example.com"],
    },
)
tracking_key = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('tracking-keys', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'name' => 'Online shop',
        'allowed_origins' => ['https://shop.example.com', '*.example.com'],
    ],
]);
$trackingKey = json_decode($response->getBody(), true);

JSON

{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "name": "Online shop",
  "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
  "allowed_origins": ["https://shop.example.com", "*.example.com"],
  "enabled": true,
  "last_used_at": null,
  "created_at": "2026-10-19T08:05:00.000000+00:00",
  "updated_at": "2026-10-19T08:05:00.000000+00:00"
}

JSON

{
  "error": "plan_required",
  "required_plan": "pro",
  "message": "Website tracking is included with Pro and Business."
}

JSON

{
  "error": "allowed_origins \"https://shop.example.com/checkout\" is not an origin (https://example.com), a host (example.com) or a wildcard (*.example.com)",
  "message": "allowed_origins \"https://shop.example.com/checkout\" is not an origin (https://example.com), a host (example.com) or a wildcard (*.example.com)",
  "errors": {
    "allowed_origins": ["\"https://shop.example.com/checkout\" is not an origin (https://example.com), a host (example.com) or a wildcard (*.example.com)"]
  }
}

Retrieve a tracking key

Retrieves a tracking key. Tracking keys are public keys for the tracking script: they go into your web pages and can only send workspace and custom events. Requires an API key with the full scope.

GET/tracking-keys/{id}

Path parameters

idstringrequired

The tracking key’s ID (trk_…) or the key itself (pub_…).

Returns

Returns the tracking key object.

objectstring

Always tracking_key.

idstring

ID of the tracking key, prefixed trk_.

namestring

Name that tells you where the key is used.

keystring

The public key: pub_ followed by 32 letters and digits. It’s part of the script URL, so it’s returned on every read.

allowed_originsstring[]

The sites that may send events with this key. Empty means any site. See Allowed sites.

enabledboolean

false when the key is turned off. Events sent with a disabled key are rejected.

last_used_atstring | null

When the key last sent events, updated at most every 10 minutes. null if it has never been used.

created_at, updated_atstring

Timestamps in UTC.

Returns 404 with error: "Tracking key not found" if no key matches.

GET/tracking-keys/{id}

Terminal

curl https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const trackingKey = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
tracking_key = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$trackingKey = json_decode($response->getBody(), true);

JSON

{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "name": "Online shop",
  "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
  "allowed_origins": ["https://shop.example.com", "*.example.com"],
  "enabled": true,
  "last_used_at": "2026-10-19T09:40:00.000000+00:00",
  "created_at": "2026-10-19T08:05:00.000000+00:00",
  "updated_at": "2026-10-19T08:05:00.000000+00:00"
}

JSON

{
  "error": "Tracking key not found"
}

Update a tracking key

Updates the fields you pass and leaves the others unchanged. The public key never changes; to replace a key, create a new one, update your pages and delete the old one. Requires an API key with the full scope.

Changes can take up to a minute to apply everywhere.

POST/tracking-keys/{id}

Path parameters

idstringrequired

The tracking key’s ID (trk_…) or the key itself (pub_…).

Body parameters

namestring

New name, up to 100 characters. Can’t be empty.

allowed_originsstring[]

Replaces the list of allowed sites, with the same rules as on create. [] allows any site.

enabledboolean

false turns the key off: the tracking script keeps loading, but its events are rejected with 403. true turns it back on.

Returns

Returns the updated tracking key object.

Status	When
`404`	No tracking key matches `id`.
`422`	A field is invalid. `errors` is keyed by field and `message` repeats the first problem.

POST/tracking-keys/{id}

Terminal

curl -X POST https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6 \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_origins": ["https://shop.example.com", "https://www.example.com"] }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ allowed_origins: ['https://shop.example.com', 'https://www.example.com'] }),
});
const trackingKey = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"allowed_origins": ["https://shop.example.com", "https://www.example.com"]},
)
tracking_key = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['allowed_origins' => ['https://shop.example.com', 'https://www.example.com']],
]);
$trackingKey = json_decode($response->getBody(), true);

JSON

{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "name": "Online shop",
  "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
  "allowed_origins": ["https://shop.example.com", "https://www.example.com"],
  "enabled": true,
  "last_used_at": "2026-10-19T09:40:00.000000+00:00",
  "created_at": "2026-10-19T08:05:00.000000+00:00",
  "updated_at": "2026-10-19T10:20:00.000000+00:00"
}

List tracking keys

Returns all of the workspace’s tracking keys, newest first. A workspace has at most 25, so the list isn’t paginated. Requires an API key with the full scope.

GET/tracking-keys

Query parameters

searchstring

Case-insensitive match on part of the name.

matchstring

all (default) requires every filter. or matches any filter. See Filtering.

orderstring

Sort key for this list. See the sort keys below.

directionstring

asc or desc.

Filter keys

Filters use key.condition=value query parameters, for example enabled.exact=true. See Filtering for the conditions per type.

Key	Type	Notes
`name`	string
`enabled`	boolean
`created_at`	date
`last_used_at`	date

Sort keys for order: name, enabled, created_at, last_used_at. The default is created_at, newest first.

Returns

dataobject[]

The tracking key objects, including each public key.

GET/tracking-keys

Terminal

curl https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/tracking-keys', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data } = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/tracking-keys",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
tracking_keys = r.json()["data"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('tracking-keys', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$trackingKeys = json_decode($response->getBody(), true)['data'];

JSON

{
  "data": [
    {
      "object": "tracking_key",
      "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
      "name": "Online shop",
      "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
      "allowed_origins": ["https://shop.example.com", "*.example.com"],
      "enabled": true,
      "last_used_at": "2026-10-19T09:40:00.000000+00:00",
      "created_at": "2026-10-19T08:05:00.000000+00:00",
      "updated_at": "2026-10-19T08:05:00.000000+00:00"
    }
  ]
}

Delete a tracking key

Deletes a tracking key. Requires an API key with the full scope.

Pages that still load the script with this key keep working, but their events are rejected and not recorded. Events already recorded with the key are kept. To stop events for a while without changing your pages, turn the key off with Update a tracking key instead.

DELETE/tracking-keys/{id}

Path parameters

idstringrequired

The tracking key’s ID (trk_…) or the key itself (pub_…).

Returns

objectstring

Always tracking_key.

idstring

ID of the deleted key.

deletedboolean

Always true.

Returns 404 if no tracking key matches.

DELETE/tracking-keys/{id}

Terminal

curl -X DELETE https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();

Python

import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);

JSON

{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "deleted": true
}