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).

Semua respons memakai amplop { "is_success", "message", "data" } kecuali disebutkan lain. Kode error umum: lihat https://apipedia.id/docs#kode-status-error.

Endpoint (8)

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.

ParameterLokasiTipeWajibKeterangan
pagequeryintegertidakDefault 1.
pageSizequeryintegertidakDefault 20.
openedquerystringtidaktrue = hanya yang sudah dibuka, false = hanya yang belum. Pilihan: true, false.
qquerystringtidakCari 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):

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).

ParameterLokasiTipeWajibKeterangan
idpathstringyaId 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.

ParameterLokasiTipeWajibKeterangan
idpathstringyaId 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.

ParameterLokasiTipeWajibKeterangan
idpathstringyaId 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.

ParameterLokasiTipeWajibKeterangan
idpathstringyaId pelacak (22 karakter) dari POST /track/emails.
eventIdpathstringyaId 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.

ParameterLokasiTipeWajibKeterangan
idpathstringyaId pelacak (22 karakter) dari POST /track/emails.
eventIdpathstringyaId 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.

ParameterLokasiTipeWajibKeterangan
idpathstringyaId pelacak (22 karakter) dari POST /track/emails.

Contoh request:

curl -X GET "https://api.apipedia.id/v1/track/open/7hQx2LmPz9RkT4vWb8NcJd.gif"

Versi Markdown halaman ini

Coba Email Tracking di Sandbox