Langue

English Italiano Deutsch Español Português (Brasil)Français

Vous cherchez une présentation générale ? Consultez la page sur l’API de vérification d’email ou sur l’API de validation d’email pour les formulaires d’inscription (en anglais).

Documentation de l’API de vérification d’adresse mail

Vérifiez une adresse mail, lancez des vérifications en masse et contrôlez en détail les adresses catch-all et protégées par une SEG. Tous les endpoints utilisent JSON et une authentification par clé API. Seules les vérifications réussies sont facturées.

Introduction

L’API Giggal.ai vous permet de vérifier une adresse mail, de lancer des vérifications en masse jusqu’à 50 000 emails par tâche et de contrôler en détail les adresses catch-all et protégées par une SEG. Elle utilise une API REST simple au format JSON. Chaque vérification réussie consomme des crédits de votre compte.

URL de base

https://api.giggal.ai/v1

Obtenir une clé API

Créez une clé API depuis votre tableau de bord Giggal.ai : ouvrez l’onglet Developer API dans la barre latérale et cliquez sur Create API Key. Chaque clé est liée à votre compte, suit sa propre utilisation et peut être révoquée à tout moment.

Ouvrir l’onglet Developer API

Format de la réponse

Chaque réponse suit la même structure JSON :

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

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

Démarrage rapide : vérifier une adresse avec 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"}'

Authentification

Envoyez votre clé API avec chaque requête, dans l’un des deux en-têtes suivants. Les deux fonctionnent.

Option 1 : jeton Bearer

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Option 2 : en-tête X-API-Key

X-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Une clé absente, invalide ou révoquée renvoie une erreur HTTP 401. N’exposez jamais vos clés API dans du code côté client. Faites passer les appels par votre backend.

Idempotence (en masse et catch-all)

Pour POST /v1/verify-batch et POST /v1/catchall, envoyez un en-tête Idempotency-Key. Une nouvelle tentative avec la même clé renvoie la réponse d’origine. Aucune tâche en double n’est créée et les crédits ne sont pas débités deux fois.

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

Vérification unitaire

1 endpoint dans ce groupe.

POST/v1/verify

Vérifier une adresse mail

Vérifie une adresse mail de façon synchrone. Coûte 1 crédit. Si le domaine est catch-all, la vérification approfondie se fait dans la même requête et la réponse inclut catch_all_score et catch_all_verdict.

Autorisations

api_key_auth

Corps de la requête

Obligatoire

string

L’adresse mail à vérifier.

POST/v1/verify

Exemples de réponse

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

Vérification en masse

3 endpoints dans ce groupe.

POST/v1/verify-batch

Envoyer une tâche de vérification en masse

Envoyez jusqu’à 50 000 emails par tâche. Le traitement est asynchrone : interrogez GET /v1/jobs/:jobId pour suivre l’avancement. Envoyez un en-tête Idempotency-Key pour relancer la création d’une tâche sans double facturation.

Autorisations

api_key_auth

Corps de la requête

emails

Obligatoire

string[]

Liste des adresses mail à vérifier. 50 000 au maximum par tâche. Les doublons et les adresses mal formées sont retirés côté serveur.

name

string

Nom facultatif de la tâche, lisible par un humain. Affiché dans votre tableau de bord.

POST/v1/verify-batch

Exemples de réponse

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

Obtenir le statut d’une tâche en masse

Interrogez cet endpoint pour suivre l’avancement. Évolution du statut : processing → completed (ou failed). Intervalle d’interrogation conseillé : 10 à 15 secondes. Les petites listes (moins de 50 emails) se terminent en général en moins de 30 secondes.

Autorisations

api_key_auth

Paramètres de chemin et de requête

jobId

Obligatoire

string

L’identifiant de tâche renvoyé par POST /v1/verify-batch.

GET/v1/jobs/:jobId

Exemples de réponse

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

Obtenir les résultats d’une tâche en masse

Quand le statut est "completed", récupérez les résultats de chaque email. Les résultats sont paginés : envoyez les paramètres de requête page et limit. Les résultats sont conservés 48 heures (voir resultsExpiresAt sur la tâche).

Autorisations

api_key_auth

Paramètres de chemin et de requête

jobId

Obligatoire

string

L’identifiant de la tâche.

page

integer

Numéro de page, 1 par défaut.

limit

integer

Résultats par page, 25 par défaut, 500 au maximum.

GET/v1/jobs/:jobId/results

Exemples de réponse

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

Vérification catch-all

4 endpoints dans ce groupe.

POST/v1/catchall

Lancer une tâche de vérification catch-all

Lance la vérification catch-all approfondie pour une tâche en masse terminée. Seules les adresses marquées catch-all dans la tâche d’origine sont vérifiées à nouveau. Facturé 1 crédit par adresse (voir creditsRequired dans la réponse).

Autorisations

api_key_auth

Corps de la requête

jobId

Obligatoire

string

L’identifiant d’une tâche de vérification en masse terminée. Seules les adresses catch-all de cette tâche sont vérifiées en détail.

name

string

Nom facultatif de la tâche, lisible par un humain.

POST/v1/catchall

Exemples de réponse

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

Obtenir le statut d’une tâche catch-all

Interrogez cet endpoint pour suivre l’avancement et les compteurs verdictCounts mis à jour. Une tâche catch-all prend en général de quelques secondes à quelques minutes, selon le volume.

Autorisations

api_key_auth

Paramètres de chemin et de requête

taskId

Obligatoire

string

L’identifiant de tâche renvoyé par POST /v1/catchall.

GET/v1/catchall/:taskId

Exemples de réponse

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

Obtenir les résultats d’une tâche catch-all

Récupère les résultats paginés de chaque email, avec le détail du score (signaux de tri du domaine et âge du domaine).

Autorisations

api_key_auth

Paramètres de chemin et de requête

taskId

Obligatoire

string

L’identifiant de la tâche.

page

integer

Numéro de page, 1 par défaut.

limit

integer

Résultats par page, 25 par défaut, 500 au maximum.

verdict

string

Filtrer par résultat : valid | invalid.

GET/v1/catchall/:taskId/results

Exemples de réponse

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

Télécharger les résultats catch-all en CSV

Télécharge tous les résultats d’une tâche catch-all terminée dans un fichier CSV avec les colonnes Email, Score et Verdict. Le Content-Type est text/csv.

Autorisations

api_key_auth

Paramètres de chemin et de requête

taskId

Obligatoire

string

L’identifiant de la tâche.

verdict

string

Filtrer par résultat : valid | invalid.

GET/v1/catchall/:taskId/download

Exemples de réponse

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"

Compte

1 endpoint dans ce groupe.

GET/v1/credits

Obtenir le solde de crédits

Renvoie le solde de votre compte : crédits disponibles, réservés (bloqués pour les tâches en cours) et totaux depuis l’ouverture du compte. Les vérifications au résultat "unknown" sont remboursées automatiquement et apparaissent ici.

Autorisations

api_key_auth

GET/v1/credits

Exemples de réponse

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

Erreurs et limites de requêtes

Statut	Signification
200 OK	La requête a réussi (vérification synchrone, ou lecture d’un statut ou de résultats).
202 Accepted	La tâche asynchrone a été créée et mise en file d’attente.
400 Bad Request	Paramètres absents ou invalides (format d’email incorrect, liste emails vide, jobId absent).
401 Unauthorized	Clé API absente, invalide ou révoquée.
402 Payment Required	Crédits insuffisants pour l’opération demandée.
404 Not Found	L’identifiant de tâche n’existe pas dans votre compte.
409 Conflict	La tâche n’est pas dans l’état requis (par exemple, résultats demandés avant la fin).
410 Gone	Les résultats de la tâche ont dépassé la durée de conservation de 48 heures.
429 Too Many Requests	Limite de requêtes dépassée. Attendez, puis réessayez.
500 / 502 / 503	Le serveur ou le service de vérification en amont est temporairement indisponible.

Limites de requêtes

Chaque réponse inclut les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (casse RFC), pour vous aider à espacer vos requêtes. RateLimit-Reset indique le nombre de secondes avant la réinitialisation de la fenêtre en cours.

Catégorie	Limite
Tous les endpoints (par défaut)	300 requêtes / 15 minutes
Création de tâches (POST /v1/verify-batch, POST /v1/catchall)	30 requêtes / 15 minutes
Suivi des tâches (GET /v1/jobs/:id, GET /v1/jobs/:id/results)	600 requêtes / 15 minutes
Nombre maximal d’emails par tâche en masse	50 000
Conservation des résultats	48 heures

Il y a trois niveaux de limite, car le suivi d’une tâche se fait plus souvent que sa création. Vous pouvez interroger l’API toutes les quelques secondes pendant qu’une tâche tourne. La limite de 600 / 15 min (environ 40 par minute) vous laisse donc de la marge sans surcharger le serveur.

Besoin de limites plus élevées ?

Nous relevons régulièrement les limites pour les partenaires d’intégration vérifiés.

Nous contacter

Format de la réponse 429

Quand vous atteignez une limite, l’API renvoie une erreur HTTP 429 avec ce corps :

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

Avant de réessayer, attendez le nombre de secondes indiqué dans l’en-tête RateLimit-Reset (temps restant avant la réinitialisation de la fenêtre).

Prêt à intégrer l’API ?

Créez votre clé API en quelques secondes. Des crédits d’essai gratuits sont inclus, pour tout tester de bout en bout avant de payer.

Obtenir votre clé API Parler à notre équipe