Bahasa

English Italiano Deutsch Español Português (Brasil)Français Nederlands Polski Bahasa Indonesia

Mencari gambaran umum? Baca halaman tentang API verifikasi email atau API validasi email untuk formulir pendaftaran (dalam bahasa Inggris).

Dokumentasi API verifikasi email

Cek alamat email, jalankan pemeriksaan massal, dan cek secara mendalam alamat catch-all serta alamat di balik SEG. Semua endpoint memakai JSON dan autentikasi dengan API key. Anda hanya membayar pemeriksaan yang berhasil.

Pengantar

Dengan API Giggal.ai, Anda bisa mengecek alamat email, menjalankan pemeriksaan massal hingga 50.000 alamat email per tugas, dan mengecek secara mendalam alamat catch-all serta alamat di balik SEG. API ini adalah REST API sederhana dengan JSON. Setiap pemeriksaan yang berhasil memakai kredit dari akun Anda.

URL dasar

https://api.giggal.ai/v1

Membuat API key

Buat API key (kunci API) di dashboard Giggal.ai Anda: buka tab Developer API di sidebar lalu klik Create API Key. Setiap key terhubung ke akun Anda dan mencatat pemakaiannya sendiri. Anda bisa mencabut key kapan saja.

Buka tab Developer API

Struktur respons

Setiap respons memiliki struktur JSON yang sama:

// Success
{ "success": true, "data": { ... }, "meta": { ... } }

// Error
{ "success": false, "error": "Human-readable error message" }

Mulai cepat: mengecek satu alamat dengan cURL

curl -X POST https://api.giggal.ai/v1/verify \
  -H "Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"info@giggal.ai"}'

Autentikasi

Kirim API key Anda di setiap permintaan, dalam salah satu dari dua header berikut. Keduanya berfungsi.

Opsi 1: Bearer token

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Opsi 2: header X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Key yang tidak ada, tidak valid, atau sudah dicabut menghasilkan error HTTP 401. Jangan pernah menaruh API key di kode sisi klien. Kirim panggilan API lewat backend Anda sendiri.

Idempotensi (massal dan catch-all)

Pada POST /v1/verify-batch dan POST /v1/catchall, kirim header Idempotency-Key. Percobaan ulang dengan key yang sama mengembalikan respons aslinya. Tidak ada tugas ganda dan kredit tidak dipotong dua kali.

Idempotency-Key: 2026-07-24-list-batch-42

Pemeriksaan satuan

1 endpoint dalam grup ini.

POST/v1/verify

Mengecek satu alamat email

Mengecek satu alamat email secara sinkron. Memakai 1 kredit. Jika domainnya catch-all, pemeriksaan mendalam dilakukan dalam permintaan yang sama dan responsnya berisi catch_all_score dan catch_all_verdict.

Otorisasi

api_key_auth

Body permintaan

Wajib

string

Alamat email yang ingin Anda cek.

POST/v1/verify

Contoh respons

{
  "success": true,
  "data": {
    "email": "info@giggal.ai",
    "is_valid": true,
    "status": "deliverable",
    "risk_level": "low",
    "deliverability_score": 89,
    "details": {
      "general": {
        "domain": "giggal.ai",
        "reason": "Mailbox confirmed deliverable"
      },
      "attributes": {
        "free_email": false,
        "role_account": false,
        "disposable": false,
        "catch_all": true,
        "has_plus_tag": false,
        "mailbox_full": false,
        "no_reply": false
      },
      "mail_server": {
        "smtp_provider": "google",
        "mx_record": "aspmx.l.google.com",
        "implicit_mx": null
      },
      "blacklist": {
        "is_blacklisted": false,
        "blacklists_found": [],
        "blacklist_reasons": [],
        "reputation_score": 100,
        "last_checked": "2026-07-23T20:47:15.540Z"
      },
      "sub_status": null
    },
    "catch_all_score": 89,
    "catch_all_verdict": "valid"
  },
  "meta": {
    "creditsUsed": 1
  }
}

Pemeriksaan massal

3 endpoint dalam grup ini.

POST/v1/verify-batch

Memulai pemeriksaan massal

Kirim hingga 50.000 alamat email per tugas. Prosesnya asinkron: panggil GET /v1/jobs/:jobId untuk memantau progresnya. Kirim header Idempotency-Key agar pembuatan tugas bisa dicoba ulang tanpa biaya ganda.

Otorisasi

api_key_auth

Body permintaan

emails

Wajib

string[]

Daftar alamat email yang ingin dicek. Maksimal 50.000 per tugas. Alamat ganda dan alamat dengan format salah dibuang oleh server.

name

string

Nama tugas yang mudah dibaca, opsional. Ditampilkan di dashboard Anda.

POST/v1/verify-batch

Contoh respons

{
  "success": true,
  "data": {
    "jobId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "processing",
    "name": "July prospect list",
    "submittedEmails": 19,
    "totalEmails": 19,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "processedEmails": 0,
    "progress": { "total": 19, "processed": 0, "percentage": 0 },
    "requestId": "e8044428-e49f-4aa2-9900-e29d73fd4071",
    "batchIds": [
      "a639b1de-0e3a-4f8a-882d-95cee9db3f99",
      "c2760ed9-eced-4222-939b-3fa4151bde93"
    ],
    "createdAt": "2026-07-23T20:47:21.908Z",
    "updatedAt": "2026-07-23T20:47:22.040Z",
    "completedAt": null,
    "resultsExpiresAt": null,
    "resultsExpired": false,
    "error": null
  },
  "meta": {
    "idempotentReplay": false,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "duplicateEmails": 0,
    "invalidEmails": 0
  }
}

GET/v1/jobs/:jobId

Melihat status tugas massal

Panggil endpoint ini untuk memantau progres. Statusnya berubah dari processing ke completed (atau failed). Interval yang disarankan: setiap 10 sampai 15 detik. Daftar kecil (kurang dari 50 alamat email) biasanya selesai dalam 30 detik.

Otorisasi

api_key_auth

Parameter path dan query

jobId

Wajib

string

ID tugas yang dikembalikan oleh POST /v1/verify-batch.

GET/v1/jobs/:jobId

Contoh respons

{
  "success": true,
  "data": {
    "jobId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "completed",
    "name": "July prospect list",
    "submittedEmails": 19,
    "totalEmails": 19,
    "acceptedEmails": 19,
    "rejectedEmails": 0,
    "processedEmails": 19,
    "progress": { "total": 19, "processed": 19, "percentage": 100 },
    "requestId": "e8044428-e49f-4aa2-9900-e29d73fd4071",
    "batchIds": [
      "a639b1de-0e3a-4f8a-882d-95cee9db3f99",
      "c2760ed9-eced-4222-939b-3fa4151bde93"
    ],
    "createdAt": "2026-07-23T20:47:21.908Z",
    "updatedAt": "2026-07-23T20:48:00.848Z",
    "completedAt": "2026-07-23T20:48:00.840Z",
    "resultsExpiresAt": "2026-07-25T20:48:00.840Z",
    "resultsExpired": false,
    "error": null
  }
}

GET/v1/jobs/:jobId/results

Mengambil hasil tugas massal

Jika statusnya "completed", ambil hasil untuk setiap alamat email. Hasilnya dibagi per halaman: kirim parameter query page dan limit. Hasil disimpan selama 48 jam (lihat resultsExpiresAt pada tugas).

Otorisasi

api_key_auth

Parameter path dan query

jobId

Wajib

string

ID tugas.

page

integer

Nomor halaman, default 1.

limit

integer

Hasil per halaman, default 25, maksimal 500.

GET/v1/jobs/:jobId/results

Contoh respons

{
  "success": true,
  "data": {
    "job": {
      "jobId": "api_job_6a627dd94559c7cd818d8fc9",
      "status": "completed",
      "name": "July prospect list",
      "totalEmails": 19,
      "processedEmails": 19,
      "completedAt": "2026-07-23T20:48:00.840Z",
      "resultsExpiresAt": "2026-07-25T20:48:00.840Z"
    },
    "results": [
      {
        "email": "hassaan@giggal.ai",
        "status": "deliverable",
        "is_valid": true,
        "risk_level": "high",
        "deliverability_score": 88,
        "details": {
          "general": {
            "domain": "giggal.ai",
            "reason": "All validations passed"
          },
          "attributes": {
            "free_email": false,
            "role_account": false,
            "disposable": false,
            "catch_all": true,
            "has_plus_tag": false,
            "mailbox_full": false,
            "no_reply": false
          },
          "mail_server": {
            "smtp_provider": "google",
            "mx_record": "aspmx.l.google.com",
            "implicit_mx": null
          },
          "blacklist": {
            "is_blacklisted": false,
            "blacklists_found": [],
            "reputation_score": 100,
            "last_checked": "2026-07-23T20:47:22.665Z"
          },
          "sub_status": null
        }
      },
      {
        "email": "zain@giggal.ai",
        "status": "deliverable",
        "is_valid": true,
        "risk_level": "low",
        "deliverability_score": 100,
        "details": { "general": { "domain": "giggal.ai", "reason": "2.1.5 OK" }, "...": "..." }
      }
    ],
    "pagination": {
      "total": 19,
      "page": 1,
      "limit": 25,
      "pages": 1
    }
  }
}

Pemeriksaan catch-all

4 endpoint dalam grup ini.

POST/v1/catchall

Memulai pemeriksaan catch-all

Menjalankan pemeriksaan catch-all mendalam untuk tugas massal yang sudah selesai. Hanya alamat yang ditandai catch-all dalam tugas asli yang dicek ulang. Memakai 1 kredit per alamat (lihat creditsRequired dalam respons).

Otorisasi

api_key_auth

Body permintaan

jobId

Wajib

string

ID tugas massal yang sudah selesai. Hanya alamat catch-all dari tugas itu yang dicek secara mendalam.

name

string

Nama tugas yang mudah dibaca, opsional.

POST/v1/catchall

Contoh respons

{
  "success": true,
  "data": {
    "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
    "sourceJobId": "api_job_6a627dd94559c7cd818d8fc9",
    "fileId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "processing",
    "name": "Catch-all round for July list",
    "totalEmails": 8,
    "processedEmails": 0,
    "progress": { "total": 8, "processed": 0, "percentage": 0 },
    "requestId": "4e7596e0-c51e-4b05-b4e9-4b8a681041fd",
    "batchIds": ["7d2b1f03-68dd-4687-be95-fcc4fbabc2e7"],
    "creditsUsed": 0,
    "creditsRequired": 8,
    "creditsPerEmail": 1,
    "verdictCounts": { "valid": 0, "invalid": 0 },
    "initiatedVia": "developer_api",
    "createdAt": "2026-07-23T20:50:51.468Z",
    "updatedAt": "2026-07-23T20:50:51.662Z",
    "lastUpdated": "2026-07-23T20:50:51.468Z"
  },
  "meta": {
    "idempotentReplay": false
  }
}

GET/v1/catchall/:taskId

Melihat status tugas catch-all

Panggil endpoint ini untuk memantau progres dan jumlah terbaru di verdictCounts. Tugas catch-all biasanya berlangsung beberapa detik sampai beberapa menit, tergantung jumlah alamat.

Otorisasi

api_key_auth

Parameter path dan query

taskId

Wajib

string

ID tugas yang dikembalikan oleh POST /v1/catchall.

GET/v1/catchall/:taskId

Contoh respons

{
  "success": true,
  "data": {
    "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
    "sourceJobId": "api_job_6a627dd94559c7cd818d8fc9",
    "fileId": "api_job_6a627dd94559c7cd818d8fc9",
    "status": "completed",
    "name": "Catch-all round for July list",
    "totalEmails": 8,
    "processedEmails": 8,
    "progress": { "total": 8, "processed": 8, "percentage": 100 },
    "requestId": "4e7596e0-c51e-4b05-b4e9-4b8a681041fd",
    "batchIds": ["7d2b1f03-68dd-4687-be95-fcc4fbabc2e7"],
    "creditsUsed": 8,
    "creditsRequired": 8,
    "creditsPerEmail": 1,
    "verdictCounts": { "valid": 1, "invalid": 7 },
    "initiatedVia": "developer_api",
    "createdAt": "2026-07-23T20:50:51.468Z",
    "updatedAt": "2026-07-23T20:50:56.646Z",
    "lastUpdated": "2026-07-23T20:50:56.583Z"
  }
}

GET/v1/catchall/:taskId/results

Mengambil hasil tugas catch-all

Mengambil hasil untuk setiap alamat email, dibagi per halaman, beserta rincian skornya (sinyal dari domain dan usia domain).

Otorisasi

api_key_auth

Parameter path dan query

taskId

Wajib

string

ID tugas.

page

integer

Nomor halaman, default 1.

limit

integer

Hasil per halaman, default 25, maksimal 500.

verdict

string

Filter berdasarkan hasil: valid | invalid.

GET/v1/catchall/:taskId/results

Contoh respons

{
  "success": true,
  "data": {
    "task": {
      "taskId": "catchall_e4194da2-c118-47c2-84bf-9c25ce8a363e",
      "status": "completed",
      "totalEmails": 8,
      "verdictCounts": { "valid": 1, "invalid": 7 }
    },
    "results": [
      {
        "email": "hassaan@giggal.ai",
        "score": 88,
        "verdict": "valid",
        "is_actually_catchall": true,
        "breakdown": {
          "domain_triage": {
            "score": 16,
            "max": 25,
            "signals": [
              "provider:google",
              "auth:partial",
              "spf:strict",
              "mx:multiple",
              "ssl:valid",
              "a_records",
              "tld:trusted"
            ],
            "ssl_cert_age_days": 22
          },
          "domain_age": {
            "score": 12,
            "max": 15,
            "signals": ["age:9y"]
          }
        }
      },
      {
        "email": "zain@giggal.ai",
        "score": 9,
        "verdict": "invalid",
        "is_actually_catchall": true,
        "breakdown": {
          "domain_triage": {
            "score": 23,
            "max": 25,
            "signals": ["provider:google", "auth:spf+dkim+dmarc", "dmarc:reject"],
            "ssl_cert_age_days": 53
          },
          "domain_age": {
            "score": 15,
            "max": 15,
            "signals": ["age:11y"]
          }
        }
      }
    ],
    "pagination": {
      "total": 8,
      "page": 1,
      "limit": 25,
      "pages": 1
    }
  }
}

GET/v1/catchall/:taskId/download

Mengunduh hasil catch-all sebagai CSV

Mengunduh semua hasil dari tugas catch-all yang sudah selesai sebagai file CSV dengan kolom Email, Score, dan Verdict. Content-Type-nya adalah text/csv.

Otorisasi

api_key_auth

Parameter path dan query

taskId

Wajib

string

ID tugas.

verdict

string

Filter berdasarkan hasil: valid | invalid.

GET/v1/catchall/:taskId/download

Contoh respons

Email,Score,Verdict
"hassaan@giggal.ai",88,"valid"
"zain@giggal.ai",9,"invalid"
"info@giggal.ai",8,"invalid"
"hassaan@giggal.ai",6,"invalid"
"zain@giggal.ai",3,"invalid"
"info@giggal.ai",8,"invalid"
"hassaan@giggal.ai",6,"invalid"
"zain@giggal.ai",9,"invalid"

Akun

1 endpoint dalam grup ini.

GET/v1/credits

Melihat saldo kredit Anda

Menampilkan saldo akun Anda: kredit yang tersedia, kredit yang dicadangkan (ditahan untuk tugas yang sedang berjalan), dan total sejak akun Anda dibuka. Pemeriksaan dengan hasil "unknown" dikembalikan otomatis dan juga tercatat di sini.

Otorisasi

api_key_auth

GET/v1/credits

Contoh respons

{
  "success": true,
  "data": {
    "balance": 145,
    "availableCredits": 145,
    "reservedCredits": 0,
    "totalPurchased": 1000,
    "totalConsumed": 92100,
    "transactionCount": 247,
    "lastTransactionAt": "2026-07-20T21:52:27.374Z"
  }
}

Error dan batas

Status	Arti
200 OK	Permintaan berhasil (pemeriksaan sinkron, atau pengambilan status atau hasil).
202 Accepted	Tugas asinkron sudah dibuat dan masuk antrean.
400 Bad Request	Parameter tidak ada atau tidak valid (format email salah, daftar emails kosong, jobId tidak ada).
401 Unauthorized	API key tidak ada, tidak valid, atau sudah dicabut.
402 Payment Required	Kredit tidak cukup untuk tindakan ini.
404 Not Found	ID tugas ini tidak ada di akun Anda.
409 Conflict	Tugas tidak berada pada status yang diperlukan (misalnya hasil diminta sebelum tugas selesai).
410 Gone	Hasil tugas sudah melewati masa simpan 48 jam.
429 Too Many Requests	Batas permintaan terlampaui. Tunggu sebentar lalu coba lagi.
500 / 502 / 503	Server atau layanan verifikasi di belakangnya sedang tidak tersedia untuk sementara.

Batas permintaan

Setiap respons berisi header RateLimit-Limit, RateLimit-Remaining, dan RateLimit-Reset (penulisan sesuai RFC), sehingga Anda bisa mengatur jarak antarpermintaan. RateLimit-Reset menunjukkan jumlah detik sampai jendela waktu saat ini dimulai ulang.

Kategori	Batas
Semua endpoint (default)	300 permintaan / 15 menit
Membuat tugas (POST /v1/verify-batch, POST /v1/catchall)	30 permintaan / 15 menit
Memantau tugas (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 permintaan / 15 menit
Jumlah maksimal alamat email per tugas massal	50.000
Masa simpan hasil	48 jam

Ada tiga batas, karena Anda lebih sering memantau tugas daripada membuatnya. Anda bisa memanggil API setiap beberapa detik selama tugas berjalan. Batas 600 / 15 min (sekitar 40 per menit) memberi Anda cukup ruang tanpa membebani server.

Butuh batas yang lebih tinggi?

Kami rutin menaikkan batas untuk mitra integrasi yang sudah terverifikasi.

Hubungi kami

Struktur respons 429

Jika Anda mencapai batas, API mengembalikan error HTTP 429 dengan body berikut:

{
  "success": false,
  "message": "Developer API rate limit exceeded"
}

Sebelum mencoba lagi, tunggu sejumlah detik yang tertulis di header RateLimit-Reset (waktu sampai jendela dimulai ulang).

Siap menghubungkan API?

Buat API key Anda dalam beberapa detik. Kredit uji coba gratis sudah termasuk, sehingga Anda bisa menguji semuanya dari awal sampai akhir sebelum membayar.

Buat API key Anda Bicara dengan tim kami