API de risco de e-mail: entregabilidade e sinais de fuga

curl

curl -X POST https://verification.didit.me/v3/email/risk/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "country_code": "US",
    "vendor_data": "lead-123",
    "metadata": {"source": "signup_prescreen"}
  }'

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{
	Email: "alice@example.com",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EmailRiskRequest;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.email().assessRisk(EmailRiskRequest.builder()
        .email("alice@example.com")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->email->assessRisk([
    'email' => 'alice@example.com',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Email.AssessRiskAsync(new EmailRiskRequest
{
    Email = "alice@example.com",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "82397be9-5921-4970-a979-2d5b43e08b33",
  "status": "Approved",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 0,
    "verified_at": null,
    "warnings": [],
    "lifecycle": [],
    "matches": [],
    "email_intelligence": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    },
    "enrichment": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    }
  },
  "vendor_data": "lead-123",
  "metadata": {
    "source": "signup_prescreen"
  },
  "created_at": "2026-09-01T10:30:00.123456+00:00"
}

POST

risk

curl

curl -X POST https://verification.didit.me/v3/email/risk/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "country_code": "US",
    "vendor_data": "lead-123",
    "metadata": {"source": "signup_prescreen"}
  }'

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{
	Email: "alice@example.com",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EmailRiskRequest;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.email().assessRisk(EmailRiskRequest.builder()
        .email("alice@example.com")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->email->assessRisk([
    'email' => 'alice@example.com',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Email.AssessRiskAsync(new EmailRiskRequest
{
    Email = "alice@example.com",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "82397be9-5921-4970-a979-2d5b43e08b33",
  "status": "Approved",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 0,
    "verified_at": null,
    "warnings": [],
    "lifecycle": [],
    "matches": [],
    "email_intelligence": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    },
    "enrichment": {
      "score": 4,
      "deliverable": "high",
      "breach_risk_level": "Low",
      "breach_risk_index": 4,
      "is_recent_breach": false,
      "is_frequent_breached": false,
      "is_disposable": false,
      "is_free_domain": false,
      "is_breached": false,
      "no_of_breaches": 0,
      "reason_codes": []
    }
  },
  "vendor_data": "lead-123",
  "metadata": {
    "source": "signup_prescreen"
  },
  "created_at": "2026-09-01T10:30:00.123456+00:00"
}

Use POST /v3/email/risk/ quando precisar de informação sobre o e-mail sem pedir ao utilizador que introduza um código de utilização única. Não envia nenhum e-mail. Cria uma sessão da API, enriquece o endereço, aplica as suas regras de risco de e-mail e devolve, numa única resposta síncrona, o mesmo bloco de e-mail normalizado usado pela Verificação de e-mail. Quando o pedido é guardado, a Didit também pode usar o e-mail pontuado como evidência agregada em Redes. Os grafos de rede podem mostrar informações de risco sobre e-mails de alto risco, contexto de fugas de dados e cobertura de perfis sociais em sinais de e-mail partilhados, mas não revelam o endereço de e-mail em bruto a outras organizações.

Interpretar a resposta

status é a decisão final para esta sessão da API. Normalmente é Approved; a avaliação de risco pode produzir In Review ou Declined.
email.is_breached, email.is_disposable e email.is_undeliverable são os sinais estáveis de sim/não para a lógica da aplicação.
email.breaches lista as fugas de dados mais recentes conhecidas que contêm o endereço, quando existe cobertura, com a data da fuga e as classes de dados expostas.
email.email_intelligence.score usa uma escala de risco de 0 a 100, em que um número mais alto significa um risco mais elevado. breach_risk_level (Low, Medium, High) e no_of_breaches são vistas derivadas.
email.email_intelligence.reason_codes explica que sinais normalizados contribuíram para o resultado. Os valores podem aumentar com o tempo, por isso não rejeite códigos desconhecidos.
email.email_intelligence e email.enrichment são alias de compatibilidade com o mesmo objeto normalizado. As novas integrações podem ler email.enrichment.
email.matches lista outras sessões da sua aplicação em que o mesmo endereço foi usado por um utilizador diferente. Use-o para a deteção de contas duplicadas.
request_id é o ID da sessão da API. Guarde-o com vendor_data se precisar de correlacionar o resultado com webhooks posteriores ou com a atividade da consola.

email.email_intelligence e email.enrichment são campos que podem não estar disponíveis. Uma pesquisa concluída pode omitir ambos quando não é devolvido nenhum dado de inteligência utilizável para esse endereço, domínio ou plano. Construa primeiro as regras com base em is_breached, is_disposable e is_undeliverable, e trate a inteligência em falta como “desconhecido”, não como “seguro”.

Complemento de presença nas redes sociais

Defina enable_social como true para adicionar um bloco email_social à resposta, em email: as plataformas online em que este endereço de e-mail está registado, agrupadas por categoria, com os totais de resumo e quaisquer detalhes de perfil que os nossos parceiros de dados devolvam.

email.email_social.profiles_registered e email.email_social.profiles_checked são os números principais: as plataformas em que o endereço de e-mail está confirmado como registado, em relação às plataformas avaliadas.
email.email_social.registered_platforms e email.email_social.not_registered_platforms listam cada plataforma com a sua category e o seu scope (global, ou local para plataformas específicas de uma região).
email.email_social.categories indica a contagem e a proporção de plataformas registadas por categoria, e email.email_social.profiles contém os detalhes de perfil por plataforma, quando uma plataforma os disponibiliza (nome, URL da fotografia, texto de apresentação, estado de privacidade e indicação de conta empresarial).
Os índices de resumo (digital_footprint_diversity, digital_sophistication_index, engagement_depth_index, subscription_affordability_index) são índices compostos numa escala de 0 a 10. Qualquer contagem pode ser null quando a verificação não devolveu dados para ela.

profiles_registered: 0 é uma resposta real, não uma falha: as plataformas foram verificadas e o endereço de e-mail não foi encontrado em nenhuma delas, o que é um sinal comum de identidade sintética. Este endpoint não age por si só com base nisso; use email_no_social_presence_action num fluxo de trabalho para o transformar num veredito de análise ou recusa. O bloco não aparece quando enable_social não está definido, nem quando a verificação de redes sociais não pôde ser concluída, caso em que a verificação não é faturada.

Comportamento no sandbox

As chaves de sandbox validam o pedido e devolvem dados determinísticos com estado aprovado. Não enviam nenhum e-mail, não consomem créditos, não criam uma sessão e não contribuem para as Redes. Com enable_social definido, devolvem também um bloco email_social determinístico.

Faturação

As chamadas à Email Risk API custam $0.04 ao preço de tabela, menos do que a Verificação de e-mail completa, porque não é enviado nenhum e-mail. Um pedido em produção é faturável assim que a pesquisa é iniciada, mesmo quando alguns campos podem não estar disponíveis. O complemento de presença nas redes sociais é faturado à parte: uma unidade email_social por pedido, além do preço da Email Risk API, sempre que a verificação é concluída. A verificação de créditos feita antes da pesquisa abrange ambos.

Autorizações

x-api-key

string

header

obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

string<email>

obrigatório

Endereço de e-mail a avaliar.

Exemplo:

"alice@example.com"

country_code

string

Sugestão opcional de país ISO 3166-1 alpha-2 ou alpha-3 para cobertura de inteligência.

Maximum string length: 3

Exemplo:

"US"

signals

object

Contexto opcional de dispositivo e rede observado pela sua aplicação. Todos os campos são opcionais. Passá-los alimenta a deteção de correspondências entre sessões em Redes.

Show child attributes

vendor_data

string

A sua referência estável para este pedido. Armazenada na sessão da API e refletida na resposta.

metadata

object | null

Os seus metadados JSON não sensíveis. Armazenados na sessão da API e devolvidos na resposta.

Quando for true, consulta também a pegada social do endereço: as plataformas de e-mail, redes sociais, profissionais, de comércio eletrónico e de entretenimento nas quais está registado. Faturado como uma unidade email_social por pedido, além do preço do próprio endpoint.

Exemplo:

true

Resposta

A avaliação de risco foi concluída. Inspecione status para verificar a decisão; o código HTTP é sempre 200 para pesquisas concluídas.

request_id

string<uuid>

obrigatório

ID da sessão de API criada para este pedido. Guarde-o com vendor_data se precisar de correlacionar o resultado com webhooks posteriores ou atividade na consola.

status

enum<string>

obrigatório

Decisão final para esta sessão de API. Normalmente Approved; a avaliação de risco pode produzir In Review ou Declined.

Opções disponíveis:

Approved,

In Review,

Declined

created_at

string<date-time>

obrigatório

Carimbo de data/hora desta resposta.

vendor_data

string | null

Eco do vendor_data que enviou, null se não tiver enviado nenhum.

metadata

object | null

Eco do objeto metadata que enviou, null se não tiver enviado nenhum.

object

Relatório de e-mail normalizado, o mesmo bloco utilizado pelas respostas da Verificação de e-mail.

Show child attributes

Última modificação em 7 de novembro de 2026

​Interpretar a resposta

​Complemento de presença nas redes sociais

​Comportamento no sandbox

​Faturação

Autorizações

Corpo

Resposta

Interpretar a resposta

Complemento de presença nas redes sociais

Comportamento no sandbox

Faturação