Email Tracking
Ketahui apakah email sudah dibuka lewat piksel pelacak 1x1.
Buat id pelacak untuk setiap email, sematkan piksel GIF 1x1 yang dikembalikan ke HTML email (atau salin piksel dari konsol dan tempel langsung di Gmail/Outlook), lalu cek status bukanya: sudah dibuka atau belum, berapa kali, kapan pertama dan terakhir, beserta riwayat event. Opsional: mulai melacak setelah N menit atau pada tanggal & jam tertentu (supaya buka oleh Anda sendiri tidak terhitung), berhenti melacak pada tanggal tertentu, abaikan buka dari proxy gambar, tandai event sebagai "Itu saya", dan webhook bertanda tangan HMAC-SHA256 saat email dibuka. Piksel bersifat publik dan tidak memotong kuota per hit; IP pembuka tidak pernah disimpan (hanya hash SHA-256). Catatan: klien yang memblokir gambar membuat email yang sudah dibaca tetap tercatat belum dibuka, dan proxy gambar Gmail atau Apple Mail Privacy Protection bisa memuat piksel secara otomatis (ditandai likelyProxy).
- Base URL:
https://api.apipedia.id/v1/track - Autentikasi:
Authorization: Bearer apk_…(token dari console.apipedia.id) - Kategori: Messaging
- Halaman: https://apipedia.id/docs/email-tracking
- OpenAPI: https://console.apipedia.id/openapi/email-tracking.yaml
Semua respons memakai amplop { "is_success", "message", "data" } kecuali disebutkan lain. Kode error umum: lihat https://apipedia.id/docs#kode-status-error.
Endpoint (8)
GET /emails: Daftar pelacak emailPOST /emails: Buat pelacak email (dapatkan URL piksel)GET /emails/{id}: Status buka satu emailPATCH /emails/{id}: Ubah pelacak emailDELETE /emails/{id}: Hapus pelacak emailPOST /emails/{id}/events/{eventId}/exclude: Kecualikan satu event ("Itu saya")POST /emails/{id}/events/{eventId}/include: Hitung kembali event yang dikecualikanGET /open/{id}.gif: Piksel pelacak (publik, disematkan di email)
Daftar pelacak email
GET https://api.apipedia.id/v1/track/emails
Pelacak milik pemanggil, terbaru dulu, berhalaman (page mulai 1, pageSize 1-100, bawaan 20). Filter opsional opened=true|false dan pencarian q (cocok sebagian di label atau recipient, tanpa beda huruf besar/kecil). Setiap item membawa status: scheduled (sebelum waktu mulai), waiting (belum dibuka), opened (minimal satu buka terhitung), atau expired (lewat expiresAt tanpa buka terhitung). webhookSecret tidak pernah ikut.
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
page | query | integer | tidak | Default 1. |
pageSize | query | integer | tidak | Default 20. |
opened | query | string | tidak | true = hanya yang sudah dibuka, false = hanya yang belum. Pilihan: true, false. |
q | query | string | tidak | Cari di label atau recipient (maks 100 karakter). |
Contoh request:
curl -X GET "https://api.apipedia.id/v1/track/emails" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
Contoh respons (200):
{
"is_success": true,
"message": "Daftar pelacak email berhasil diambil",
"data": {
"items": [
{
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"label": "Promo Oktober",
"recipient": "[email protected]",
"metadata": {
"campaign": "okt-2026"
},
"status": "opened",
"opened": true,
"openCount": 2,
"humanOpenCount": 1,
"likelyProxyOnly": false,
"firstOpenedAt": "2026-10-29T03:20:11Z",
"lastOpenedAt": "2026-10-29T08:02:45Z",
"startAt": "2026-10-29T03:20:00Z",
"expiresAt": null,
"countProxyAsOpen": true,
"webhook": {
"url": "https://contoh.com/webhooks/apipedia",
"events": "first",
"lastDeliveryAt": "2026-10-29T03:20:12Z",
"lastStatus": "200"
},
"createdAt": "2026-10-29T03:15:00Z",
"pixelUrl": "https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif",
"htmlSnippet": "<img src=\"https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif\" width=\"1\" height=\"1\" alt=\"\" style=\"display:none\">",
"statusUrl": "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd"
}
],
"page": 1,
"pageSize": 20,
"total": 1
}
}
Buat pelacak email (dapatkan URL piksel)
POST https://api.apipedia.id/v1/track/emails
Langkah 1 Email Tracking: membuat id pelacak acak (22 karakter base62, tidak berurutan dan tidak bisa ditebak) untuk SATU email. Sematkan htmlSnippet (atau <img> ke pixelUrl) di HTML email yang Anda kirim; setiap kali klien email memuat gambar itu, buka-nya tercatat. Cek hasilnya lewat statusUrl (GET /track/emails/{id}).
Body (semua opsional):
label(maks 200 karakter),recipient(maks 320 karakter),metadata(objek JSON bebas, maks 2 KB).- Jadwal mulai - isi SALAH SATU:
startAfterMinutes(bilangan bulat 0-525600) ataustartAt(ISO 8601 WAJIB dengan zona waktu, mis.2026-11-01T09:00:00+07:00; waktu lampau = sekarang). Bawaan: mulai sekarang. Buka sebelum waktu mulai (mis. Anda membuka email di folder Terkirim) tetap tercatat sebagai event denganignoredReason: "before_start"tetapi tidak dihitung. expiresAt(ISO 8601 dengan zona waktu, di masa depan, sesudah waktu mulai): buka sesudahnya dicatat denganignoredReason: "expired"dan tidak dihitung.countProxyAsOpen(bawaantrue):false= buka dari proxy gambar (likelyProxy) tidak mengubah status menjadi dibuka dan tidak dihitung diopenCount.webhookUrl(https saja, maks 2048 karakter, host privat/lokal ditolak) danwebhookEvents:first(bawaan, hanya buka terhitung pertama) atauevery(setiap buka terhitung).
Bila webhookUrl diisi, respons membawa webhookSecret (apwh_...) SATU KALI SAJA - simpan, karena tidak pernah ditampilkan lagi (putar lewat PATCH rotateWebhookSecret: true).
Webhook. Pada buka yang terhitung (di dalam jendela mulai/kedaluwarsa, tidak dikecualikan, lolos aturan proxy) APIPedia mengirim POST JSON ke webhookUrl:
{"event":"email.opened","trackerId":"7hQx2LmPz9RkT4vWb8NcJd","eventId":42,"label":"Promo Oktober","recipient":"[email protected]","metadata":{"campaign":"okt-2026"},"openedAt":"2026-10-29T03:20:11Z","openCount":1,"firstOpen":true,"likelyProxy":false,"userAgent":"Mozilla/5.0 ... Thunderbird/128.0"}
Header: X-APIPedia-Event: email.opened, X-APIPedia-Delivery: <uuid> (sama untuk percobaan ulang - pakai untuk membuang duplikat), X-APIPedia-Signature: sha256=<hex>. Tanda tangan = HMAC-SHA256 dari BODY MENTAH (byte persis yang diterima, sebelum di-parse) dengan webhookSecret sebagai kunci, ditulis hex huruf kecil. Verifikasi (Node.js):
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-apipedia-signature']));
Pengiriman berjalan sesudah piksel dijawab, timeout 5 detik, 1x percobaan ulang untuk error jaringan/timeout/408/429/5xx, redirect tidak diikuti. Balas 2xx secepatnya. Hasil terakhir tampil di webhook.lastStatus (kode HTTP, timeout, network_error, blocked_url, atau blocked_address bila host me-resolve ke alamat privat).
Catatan penting: piksel hanya bisa membuktikan GAMBAR dimuat. Klien yang memblokir gambar membuat email yang sudah dibaca tetap tercatat belum dibuka ("belum dibuka" bukan berarti "belum dibaca"). Sebaliknya, proxy gambar Gmail (GoogleImageProxy) dan Apple Mail Privacy Protection bisa memuat piksel secara otomatis tanpa email dibuka manusia; event seperti itu ditandai likelyProxy: true.
Body (application/json):
{
"label": "Promo Oktober",
"recipient": "[email protected]",
"metadata": {
"campaign": "okt-2026",
"userId": 42
},
"startAfterMinutes": 5,
"expiresAt": "2026-11-30T00:00:00+07:00",
"countProxyAsOpen": true,
"webhookUrl": "https://contoh.com/webhooks/apipedia",
"webhookEvents": "first"
}
Contoh request:
curl -X POST "https://api.apipedia.id/v1/track/emails" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"label":"Promo Oktober","recipient":"[email protected]","metadata":{"campaign":"okt-2026","userId":42},"startAfterMinutes":5,"expiresAt":"2026-11-30T00:00:00+07:00","countProxyAsOpen":true,"webhookUrl":"https://contoh.com/webhooks/apipedia","webhookEvents":"first"}'
Contoh respons (200):
{
"is_success": true,
"message": "Pelacak email berhasil dibuat",
"data": {
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"label": "Promo Oktober",
"recipient": "[email protected]",
"metadata": {
"campaign": "okt-2026",
"userId": 42
},
"status": "scheduled",
"opened": false,
"openCount": 0,
"humanOpenCount": 0,
"likelyProxyOnly": false,
"firstOpenedAt": null,
"lastOpenedAt": null,
"startAt": "2026-10-29T03:20:00Z",
"expiresAt": "2026-11-29T17:00:00Z",
"countProxyAsOpen": true,
"webhook": {
"url": "https://contoh.com/webhooks/apipedia",
"events": "first",
"lastDeliveryAt": null,
"lastStatus": null
},
"createdAt": "2026-10-29T03:15:00Z",
"pixelUrl": "https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif",
"htmlSnippet": "<img src=\"https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif\" width=\"1\" height=\"1\" alt=\"\" style=\"display:none\">",
"statusUrl": "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd",
"webhookSecret": "apwh_CONTOH-rahasia-hanya-tampil-sekali-xxxxxxxx"
}
}
Status buka satu email
GET https://api.apipedia.id/v1/track/emails/{id}
Langkah 3 Email Tracking: status, opened, openCount, humanOpenCount (buka terhitung yang bukan dari proxy gambar), likelyProxyOnly (dibuka tetapi semua bukanya dari proxy), firstOpenedAt, lastOpenedAt (hanya buka TERHITUNG), jadwal (startAt, expiresAt), webhook, dan 50 event terakhir { id, at, userAgent, likelyProxy, ignoredReason, excluded, excludedAt, counted }. Event dengan ignoredReason (before_start / expired) atau excluded: true ("Itu saya") tidak dihitung; begitu juga event proxy bila countProxyAsOpen false. humanOpenSeen true bila setidaknya satu event terhitung BUKAN dari proxy gambar - bukti terkuat yang bisa diberikan piksel bahwa email dibuka manusia. Alamat IP pembuka tidak pernah disimpan maupun dikembalikan. Hanya pemilik pelacak yang bisa membacanya (id milik orang lain dijawab 404).
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
id | path | string | ya | Id pelacak (22 karakter) dari POST /track/emails. |
Contoh request:
curl -X GET "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
Contoh respons (200):
{
"is_success": true,
"message": "Status pelacak email berhasil diambil",
"data": {
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"label": "Promo Oktober",
"recipient": "[email protected]",
"metadata": {
"campaign": "okt-2026"
},
"status": "opened",
"opened": true,
"openCount": 2,
"humanOpenCount": 1,
"likelyProxyOnly": false,
"firstOpenedAt": "2026-10-29T03:25:40Z",
"lastOpenedAt": "2026-10-29T08:02:45Z",
"startAt": "2026-10-29T03:20:00Z",
"expiresAt": null,
"countProxyAsOpen": true,
"webhook": {
"url": "https://contoh.com/webhooks/apipedia",
"events": "first",
"lastDeliveryAt": "2026-10-29T03:25:41Z",
"lastStatus": "200"
},
"createdAt": "2026-10-29T03:15:00Z",
"pixelUrl": "https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif",
"htmlSnippet": "<img src=\"https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif\" width=\"1\" height=\"1\" alt=\"\" style=\"display:none\">",
"statusUrl": "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd",
"humanOpenSeen": true,
"events": [
{
"id": "1042",
"at": "2026-10-29T08:02:45Z",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Thunderbird/128.0",
"likelyProxy": false,
"ignoredReason": null,
"excluded": false,
"excludedAt": null,
"counted": true
},
{
"id": "1041",
"at": "2026-10-29T03:25:40Z",
"userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
"likelyProxy": true,
"ignoredReason": null,
"excluded": false,
"excludedAt": null,
"counted": true
},
{
"id": "1040",
"at": "2026-10-29T03:16:02Z",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
"likelyProxy": false,
"ignoredReason": "before_start",
"excluded": false,
"excludedAt": null,
"counted": false
}
]
}
}
Ubah pelacak email
PATCH https://api.apipedia.id/v1/track/emails/{id}
Hanya field yang DIKIRIM yang berubah. label, recipient, metadata, expiresAt, webhookUrl boleh null untuk menghapus. Jadwal mulai: startAt (ISO 8601 dengan zona waktu; boleh di masa lalu, dipotong ke waktu pembuatan pelacak) atau startAfterMinutes (dari sekarang); startAt: null = mulai sekarang. Mengubah startAt, expiresAt, atau countProxyAsOpen mengklasifikasi ulang SEMUA event tersimpan dan menghitung ulang openCount/firstOpenedAt/lastOpenedAt (webhook tidak dikirim untuk buka lama yang menjadi terhitung). webhookEvents: first | every. rotateWebhookSecret: true membuat rahasia baru.
webhookSecret di respons hanya terisi bila rahasia BARU dibuat (webhook pertama kali dipasang, atau diputar); selain itu null. Menghapus webhookUrl ikut menghapus rahasianya. Field lain dijawab 400.
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
id | path | string | ya | Id pelacak (22 karakter) dari POST /track/emails. |
Body (application/json, wajib):
{
"label": "Promo Oktober (follow-up)",
"expiresAt": "2026-12-31T23:59:00+07:00",
"webhookEvents": "every"
}
Contoh request:
curl -X PATCH "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"label":"Promo Oktober (follow-up)","expiresAt":"2026-12-31T23:59:00+07:00","webhookEvents":"every"}'
Contoh respons (200):
{
"is_success": true,
"message": "Pelacak email berhasil diperbarui",
"data": {
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"label": "Promo Oktober (follow-up)",
"recipient": "[email protected]",
"metadata": {
"campaign": "okt-2026"
},
"status": "opened",
"opened": true,
"openCount": 2,
"humanOpenCount": 1,
"likelyProxyOnly": false,
"firstOpenedAt": "2026-10-29T03:25:40Z",
"lastOpenedAt": "2026-10-29T08:02:45Z",
"startAt": "2026-10-29T03:20:00Z",
"expiresAt": "2026-12-31T16:59:00Z",
"countProxyAsOpen": true,
"webhook": {
"url": "https://contoh.com/webhooks/apipedia",
"events": "every",
"lastDeliveryAt": "2026-10-29T03:25:41Z",
"lastStatus": "200"
},
"createdAt": "2026-10-29T03:15:00Z",
"pixelUrl": "https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif",
"htmlSnippet": "<img src=\"https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif\" width=\"1\" height=\"1\" alt=\"\" style=\"display:none\">",
"statusUrl": "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd",
"webhookSecret": null
}
}
Hapus pelacak email
DELETE https://api.apipedia.id/v1/track/emails/{id}
Menghapus pelacak beserta seluruh event-nya. Sesudahnya piksel tetap menjawab GIF (supaya email lama tidak menampilkan gambar rusak) tetapi tidak ada yang dicatat lagi.
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
id | path | string | ya | Id pelacak (22 karakter) dari POST /track/emails. |
Contoh request:
curl -X DELETE "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
Contoh respons (200):
{
"is_success": true,
"message": "Pelacak email berhasil dihapus",
"data": {
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"deleted": true
}
}
Kecualikan satu event ("Itu saya")
POST https://api.apipedia.id/v1/track/emails/{id}/events/{eventId}/exclude
Menandai satu event sebagai buka oleh Anda sendiri (mis. pratinjau di folder Terkirim). Event tetap tersimpan dan terlihat dengan excluded: true, tetapi tidak dihitung: openCount, firstOpenedAt, lastOpenedAt, dan status dihitung ulang dari event yang tersisa. Respons = detail pelacak yang sudah diperbarui (bentuk sama dengan GET /track/emails/{id}). Event milik pelacak lain atau id yang tidak ada dijawab 404. Webhook yang sudah terkirim tidak ditarik.
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
id | path | string | ya | Id pelacak (22 karakter) dari POST /track/emails. |
eventId | path | string | ya | Id event dari events[].id di GET /track/emails/{id}. |
Contoh request:
curl -X POST "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd/events/1042/exclude" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
Contoh respons (200):
{
"is_success": true,
"message": "Event dikecualikan dari hitungan",
"data": {
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"status": "opened",
"opened": true,
"openCount": 1,
"humanOpenCount": 1,
"likelyProxyOnly": false,
"firstOpenedAt": "2026-10-29T03:25:40Z",
"lastOpenedAt": "2026-10-29T03:25:40Z",
"humanOpenSeen": false,
"events": [
{
"id": "1042",
"at": "2026-10-29T08:02:45Z",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Thunderbird/128.0",
"likelyProxy": false,
"ignoredReason": null,
"excluded": true,
"excludedAt": "2026-10-29T09:00:00Z",
"counted": false
}
]
}
}
Hitung kembali event yang dikecualikan
POST https://api.apipedia.id/v1/track/emails/{id}/events/{eventId}/include
Membatalkan "Itu saya": event kembali dihitung (selama berada di dalam jendela mulai/kedaluwarsa dan lolos aturan proxy), lalu agregat dihitung ulang. Respons = detail pelacak yang sudah diperbarui. Tidak mengirim webhook.
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
id | path | string | ya | Id pelacak (22 karakter) dari POST /track/emails. |
eventId | path | string | ya | Id event dari events[].id di GET /track/emails/{id}. |
Contoh request:
curl -X POST "https://api.apipedia.id/v1/track/emails/7hQx2LmPz9RkT4vWb8NcJd/events/1042/include" \
-H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
Contoh respons (200):
{
"is_success": true,
"message": "Event dihitung kembali",
"data": {
"id": "7hQx2LmPz9RkT4vWb8NcJd",
"status": "opened",
"opened": true,
"openCount": 2,
"humanOpenCount": 1,
"likelyProxyOnly": false,
"firstOpenedAt": "2026-10-29T03:25:40Z",
"lastOpenedAt": "2026-10-29T08:02:45Z",
"humanOpenSeen": true,
"events": [
{
"id": "1042",
"at": "2026-10-29T08:02:45Z",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Thunderbird/128.0",
"likelyProxy": false,
"ignoredReason": null,
"excluded": false,
"excludedAt": null,
"counted": true
}
]
}
}
Piksel pelacak (publik, disematkan di email)
GET https://api.apipedia.id/v1/track/open/{id}.gif
Endpoint publik: tidak butuh token.
Langkah 2 Email Tracking ("proses id"): URL inilah yang dimuat klien email. PUBLIK, tanpa token. Selalu menjawab GIF transparan 1x1 (image/gif, 43 byte) dengan Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache, Expires: 0 - juga untuk id yang tidak dikenal atau sudah dihapus (keberadaan id tidak bisa ditebak dari respons; hit seperti itu tidak dicatat).
Setiap hit mencatat waktu, user agent, hash SHA-256 IP (IP mentah tidak disimpan), dan likelyProxy (GoogleImageProxy, Apple Mail Privacy Protection, YahooMailProxy, user agent kosong). Hit ulang dari IP dan user agent yang sama dalam 10 detik dibuang, dan lebih dari 60 hit per menit per pelacak diabaikan. Buka sebelum startAt atau sesudah expiresAt dicatat sebagai event yang diabaikan (ignoredReason) dan tidak memicu webhook. Hit piksel TIDAK dihitung ke kuota atau log pemilik pelacak. Anda tidak perlu memanggil endpoint ini sendiri.
| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
id | path | string | ya | Id pelacak (22 karakter) dari POST /track/emails. |
Contoh request:
curl -X GET "https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif"