Chiavi di tracciamento

Gestisci le chiavi pubbliche che lo script di tracciamento usa per inviare eventi dal tuo sito web.

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

Crea una chiave di tracciamento

Crea una chiave di tracciamento per lo script di tracciamento. La risposta include la key pubblica da inserire nell’URL dello script. Richiede una chiave API con il permesso full.

Le chiavi di tracciamento sono pubbliche, quindi chiunque può copiarne una dalla tua pagina. Possono solo inviare eventi di workspace e personalizzati, mai leggere dati, e puoi limitarle ai tuoi siti con allowed_origins. Un workspace può avere fino a 25 chiavi di tracciamento.

Il tracciamento del sito web è incluso nei piani Pro, Business e Custom. Le chiavi restano dopo il passaggio a Pay as you go, ma le richieste dello script di tracciamento che le usano restituiscono 403.

POST/tracking-keys

Parametri del corpo

namestringpredefinito: Website

Nome che indica dove viene usata la chiave, ad esempio Online shop, fino a 100 caratteri.

allowed_originsstring[]

I siti autorizzati a inviare eventi con la chiave, fino a 50. Vuoto o omesso significa qualsiasi sito. Ogni voce è una delle seguenti:

un’origine, come https://shop.example.com: solo quello schema, quell’host e quella porta;
un host, come shop.example.com: quell’host con qualsiasi schema o porta;
un carattere jolly, come *.example.com: example.com e tutti i suoi sottodomini.

Le voci vengono memorizzate in minuscolo, senza barra finale. Viene accettata anche una stringa con le voci separate da spazi o virgole.

enabledbooleanpredefinito: true

false crea la chiave disattivata.

Restituisce

Restituisce 201 Created con l’oggetto chiave di tracciamento.

Stato	Quando
`403`	La chiave API non ha il permesso `full`, oppure il workspace è su Pay as you go: `error` è `plan_required` e `required_plan` è `pro`.
`422`	Un campo non è valido, ad esempio una voce di `allowed_origins` che non è un’origine, un host o un carattere jolly. `errors` ha come chiave il campo e `message` ripete il primo problema. Viene restituito anche con `code: "tracking_keys_limit"` quando il workspace ha già 25 chiavi di tracciamento.

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)"]
  }
}

Recupera una chiave di tracciamento

Recupera una chiave di tracciamento. Le chiavi di tracciamento sono chiavi pubbliche per lo script di tracciamento: vanno inserite nelle tue pagine web e possono solo inviare eventi di workspace e personalizzati. Richiede una chiave API con il permesso full.

GET/tracking-keys/{id}

Parametri di percorso

idstringobbligatorio

L’ID della chiave di tracciamento (trk_…) o la chiave stessa (pub_…).

Restituisce

Restituisce l’oggetto chiave di tracciamento.

objectstring

Sempre tracking_key.

idstring

ID della chiave di tracciamento, con prefisso trk_.

namestring

Nome che indica dove viene usata la chiave.

keystring

La chiave pubblica: pub_ seguito da 32 lettere e cifre. Fa parte dell’URL dello script, quindi viene restituita a ogni lettura.

allowed_originsstring[]

I siti che possono inviare eventi con questa chiave. Vuoto significa qualsiasi sito. Vedi Siti autorizzati.

enabledboolean

false quando la chiave è disattivata. Gli eventi inviati con una chiave disattivata vengono rifiutati.

last_used_atstring | null

Quando la chiave ha inviato eventi l’ultima volta, aggiornato al massimo ogni 10 minuti. null se non è mai stata usata.

created_at, updated_atstring

Timestamp in UTC.

Restituisce 404 con error: "Tracking key not found" se nessuna chiave corrisponde.

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"
}

Aggiorna una chiave di tracciamento

Aggiorna i campi che passi e lascia invariati gli altri. La key pubblica non cambia mai; per sostituire una chiave, creane una nuova, aggiorna le tue pagine ed elimina quella vecchia. Richiede una chiave API con il permesso full.

Le modifiche possono richiedere fino a un minuto per essere applicate ovunque.

POST/tracking-keys/{id}

Parametri di percorso

idstringobbligatorio

L’ID della chiave di tracciamento (trk_…) o la chiave stessa (pub_…).

Parametri del corpo

namestring

Nuovo nome, fino a 100 caratteri. Non può essere vuoto.

allowed_originsstring[]

Sostituisce l’elenco dei siti autorizzati, con le stesse regole valide in creazione. [] consente qualsiasi sito.

enabledboolean

false disattiva la chiave: lo script di tracciamento continua a caricarsi, ma i suoi eventi vengono rifiutati con 403. true la riattiva.

Restituisce

Restituisce l’oggetto chiave di tracciamento aggiornato.

Stato	Quando
`404`	Nessuna chiave di tracciamento corrisponde a `id`.
`422`	Un campo non è valido. `errors` ha come chiave il campo e `message` ripete il primo problema.

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"
}

Elenca le chiavi di tracciamento

Restituisce tutte le chiavi di tracciamento del workspace, a partire dalla più recente. Un workspace ne ha al massimo 25, quindi l’elenco non è paginato. Richiede una chiave API con il permesso full.

GET/tracking-keys

Parametri di query

searchstring

Corrispondenza su una parte del nome, senza distinzione tra maiuscole e minuscole.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri. or richiede che ne corrisponda almeno uno. Vedi Filtri e ordinamento.

orderstring

Chiave di ordinamento di questo elenco. Vedi le chiavi di ordinamento qui sotto.

directionstring

asc o desc.

Chiavi di filtro

I filtri usano parametri di query key.condition=value, ad esempio enabled.exact=true. Per le condizioni di ogni tipo, vedi Filtri e ordinamento.

Chiave	Tipo	Note
`name`	string
`enabled`	boolean
`created_at`	date
`last_used_at`	date

Chiavi di ordinamento per order: name, enabled, created_at, last_used_at. Il valore predefinito è created_at, a partire dalla più recente.

Restituisce

dataobject[]

Gli oggetti chiave di tracciamento, compresa la key pubblica di ciascuno.

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"
    }
  ]
}

Elimina una chiave di tracciamento

Elimina una chiave di tracciamento. Richiede una chiave API con il permesso full.

Le pagine che caricano ancora lo script con questa chiave continuano a funzionare, ma i loro eventi vengono rifiutati e non vengono registrati. Gli eventi già registrati con la chiave vengono conservati. Per fermare gli eventi per un po’ senza modificare le tue pagine, disattiva invece la chiave con Aggiorna una chiave di tracciamento.

DELETE/tracking-keys/{id}

Parametri di percorso

idstringobbligatorio

L’ID della chiave di tracciamento (trk_…) o la chiave stessa (pub_…).

Restituisce

objectstring

Sempre tracking_key.

idstring

L’ID della chiave eliminata.

deletedboolean

Sempre true.

Restituisce 404 se nessuna chiave di tracciamento corrisponde.

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
}