Beta privataMailbeam è in beta privata: l'API pubblica non è ancora aperta.Iscriviti alla lista d'attesa

Errori

Mailbeam usa codici di stato HTTP standard. Tutte le risposte di errore includono un campo error leggibile dalla macchina e un message leggibile dalle persone.

Struttura di una risposta di errore

{
  "error": "invalid_email_format",
  "message": "The email address is not RFC 5322 compliant.",
  "request_id": "req_01hx9abc123"
}

Nel tuo codice controlla sempre il campo error: message può cambiare, error è stabile.

Codici di stato HTTP

CodiceSignificato
200La richiesta è andata a buon fine
400Richiesta errata: controlla il corpo
401L'autenticazione è fallita
403Vietato: permessi insufficienti
422Errore di validazione: l'indirizzo ha un problema preciso
413Il corpo della richiesta è troppo grande
429Limite di ritmo o quota superati
500Errore interno del server: contatta l'assistenza
503Capacità non disponibile in questa pubblicazione

Codici di errore

Errori di autenticazione

ErroreStatoDescrizione
missing_api_key401Non c'è l'intestazione Authorization
invalid_api_key401Il formato della chiave non è valido
revoked_api_key401La chiave è stata revocata
insufficient_permissions403La chiave non ha l'ambito necessario

Errori di validazione

ErroreStatoDescrizione
invalid_email_format422L'email non rispetta la sintassi dell'RFC 5322
email_too_long422L'email supera i 254 caratteri
missing_required_field400Manca un campo obbligatorio nel corpo
invalid_json400Il corpo della richiesta non è JSON valido
invalid_request400Il JSON è ben formato ma non è valido: per esempio un URL di webhook che non è HTTPS
payload_too_large413Il corpo supera il limite di dimensione di quell'endpoint

Errori di limite di ritmo

ErroreStatoDescrizione
rate_limit_exceeded429Limite al secondo raggiunto; guarda retry_after
quota_exceeded429Quota mensile esaurita (il piano Free blocca; quelli a pagamento proseguono con fatturazione per eccedenza)

Errori del server

ErroreStatoDescrizione
internal_error500Errore transitorio del server: riprova con rallentamento
service_unavailable503Una capacità non è configurata in questa pubblicazione
upstream_timeout504Il sondaggio SMTP ha esaurito il tempo; il risultato non è conclusivo

Gestire gli errori nel tuo codice

try {
  const result = await verifyEmail(email);
  if (!result.valid) {
    // L'email non è valida ma la richiesta è andata bene: questo NON è un errore
    handleInvalidEmail(result.reason);
  }
} catch (err) {
  switch (err.code) {
    case "rate_limit_exceeded":
      await sleep(err.retryAfter * 1000);
      // riprova
      break;
    case "quota_exceeded":
      // Avvisa chi tiene i sistemi, usa un piano B oppure lascia passare la registrazione
      notifyOpsTeam();
      break;
    case "invalid_api_key":
    case "revoked_api_key":
      // Allerta: è un problema di configurazione
      alertPagerDuty("chiave API di Mailbeam non valida");
      break;
    default:
      // Registra e prosegui: non bloccare gli utenti per errori imprevisti
      logger.error("Errore di Mailbeam", { code: err.code, requestId: err.requestId });
  }
}

Il campo reason

Quando valid è false, il campo reason contiene una stringa leggibile dalla macchina che spiega perché:

MotivoSpiegazione
invalid_syntaxNon supera il controllo di formato dell'RFC 5322
no_mx_recordsIl dominio non ha server di posta, oppure pubblica un MX nullo
domain_not_foundIl dominio non si risolve affatto
smtp_rejectedLa casella non esiste
mailbox_fullLa casella esiste ma ha superato la sua quota
disposable_domainCombacia con un fornitore di posta temporanea
role_addressSembra un indirizzo non personale
catch_all_unverifiableIl dominio accetta tutta la posta; l'SMTP non è conclusivo
greylistedIl server ci ha chiesto di tornare più tardi: trattalo come sconosciuto
smtp_blockedIl server ha rifiutato il nostro sondaggio, non l'indirizzo
smtp_unreachableNessun server di posta ha risposto
timeoutIl sondaggio ha esaurito il tempo: trattalo come sconosciuto

status contro valid

valid è un booleano, e con due stati non si può distinguere «questa casella non esiste» da «non siamo riusciti a saperlo». Usa status quando quella differenza conta:

StatoSignificatovalid
deliverableLa casella è stata confermatatrue
undeliverableConfermato come cattivo: sintassi errata, nessuna via per la posta, casella rifiutata, usa e gettafalse
riskyReale ma di bassa qualità: dominio catch-all, indirizzo di ruolo, casella pienafalse
unknownNon siamo riusciti a saperlo: greylisting, sondaggio bloccato, DNS scadutofalse

Bloccare le registrazioni per undeliverable è sicuro. Bloccare per unknown blocca utenti veri: usa invece lo score.

Non bloccare mai un utente solo per catch_all_unverifiable. Usa il campo score per prendere decisioni con sfumature.