Errori e limiti dell’API email: codici di stato, retry e monitoraggio

Inviare un’email in una demo è facile. Inviarne centomila al mese in produzione significa prepararsi ai momenti in cui qualcosa va storto: una chiave revocata, una carta scaduta, un mese che finisce prima del previsto, un server di posta in una giornata no.

Questa guida spiega ogni risposta restituita dall’endpoint di invio di Inbixio, cosa deve fare il tuo codice in ciascun caso e come tenere d’occhio il recapito una volta in produzione.

Due fasi: accettata, poi recapitata

Una chiamata a POST /api/send-email/ avviene in due fasi:

1. La richiesta API. Inbixio verifica la chiave, i suoi permessi, l’abbonamento, l’utilizzo mensile e il corpo della richiesta. Se tutto è in ordine, restituisce 200 e mette il messaggio in coda.
2. Il recapito. Un attimo dopo Inbixio si collega al tuo server SMTP e gli consegna il messaggio. Ogni messaggio viene registrato come inviato o non riuscito, e questi risultati alimentano i dati della dashboard.

Quindi un 200 significa “accettata per il recapito”, non “arrivata in inbox”. I problemi della fase 1 tornano come errori HTTP che il tuo codice può gestire. I problemi della fase 2, come una password SMTP errata, emergono nella percentuale di recapiti non riusciti della dashboard. Inbixio effettua un solo tentativo di recapito per messaggio e non ritenta un recapito non riuscito.

Ogni risposta e cosa fare

I messaggi di errore arrivano nel campo error per la maggior parte delle risposte e nel campo detail per gli errori di autenticazione, quindi leggili entrambi:

const body = await res.json().catch(() => ({}));
const reason = body.error ?? body.detail ?? res.statusText;

Ritenta solo ciò che può riuscire

Ritentare un 401 cento volte non renderà valida la chiave: riempirà soltanto i log. Dividi gli errori in due gruppi:

• Da ritentare: errori di rete, timeout, risposte 5xx e il 429 del rate limit (quello con un messaggio in detail). Attendi quanto indica l’header Retry-After, altrimenti usa un backoff esponenziale con jitter, e rinuncia dopo qualche tentativo.
• Da non ritentare: 400, 401, 402, 403 e il 429 del limite mensile (quello con limit e sent). Richiedono l’intervento di una persona o una richiesta diversa. Registrali nei log in modo ben visibile e imposta avvisi su 401, 402 e sul 429 del limite mensile, perché bloccano tutte le tue email.

// 5xx and the short-term rate limit can succeed later; the monthly limit (body has `limit`) can't.
const retryable = (status, body) => status >= 500 || (status === 429 && body.limit === undefined);

export async function sendWithRetry(payload, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    let res;
    try {
      res = await fetch('https://backend.inbixio.com/api/send-email/', {
        method: 'POST',
        headers: { 'X-API-Key': process.env.INBIXIO_API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(15_000),
      });
    } catch (err) {
      if (i === attempts - 1) throw err; // network error or timeout: retry
    }
    if (res?.ok) return res.json();
    if (res) {
      const body = await res.json().catch(() => ({}));
      if (!retryable(res.status, body)) {
        throw new Error(`Inbixio ${res.status}: ${body.error ?? body.detail ?? res.statusText}`);
      }
    }
    const retryAfter = Number(res?.headers.get('Retry-After')) * 1000;
    const delay = retryAfter || Math.min(30_000, 1000 * 2 ** i) * (0.5 + Math.random()); // 0.5s–30s with jitter
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error('Inbixio: gave up after retries');
}

Attenzione ai duplicati: se una richiesta va in timeout, potrebbe essere stata comunque accettata. Ritentarla potrebbe quindi inviare la stessa email due volte. Per ricevute e notifiche di solito è accettabile; quando un duplicato confonderebbe gli utenti, registra ciò che hai inviato nel tuo database e controllalo prima di ritentare.

Limiti mensili

Ogni piano include un certo numero di email al mese: 25.000 con Starter e 150.000 con Growth. Inbixio conta le email inviate correttamente nel mese di calendario in corso. Quando raggiungi il limite, gli invii restituiscono 429 con il tuo limit e il conteggio sent attuale, finché non inizia il mese successivo o passi a un piano superiore.

Non aspettare il 429:

• La pagina API Keys (chiavi API) mostra una scheda Usage Limit (limite di utilizzo) con le email inviate questo mese rispetto al limite del piano.
• Imposta un promemoria per controllarla quando arrivi a circa l’80% del limite e pianifica il cambio di piano prima di un grande lancio o di un’importazione.
• Per una stima del volume passo per passo, leggi come scegliere un piano API email.

Recapiti non riusciti (fase 2)

Quando l’API ha accettato un messaggio ma il tuo server SMTP l’ha rifiutato, conta come recapito non riuscito. La dashboard mostra la percentuale Failed Deliveries (recapiti non riusciti) degli ultimi 7 giorni, non un elenco dei singoli messaggi, quindi tieni d’occhio la percentuale e controlla le impostazioni del server quando sale. Le cause più comuni:

• Autenticazione non riuscita: la password della casella è cambiata, oppure il provider ora richiede una password per le app.
• Problemi di connessione: l’host o la porta nelle impostazioni del server sono errati.
• Limiti del provider: il tuo provider di posta ha limitato l’invio giornaliero della casella.
• Destinatario rifiutato: il tuo server ha rifiutato l’indirizzo durante l’invio. I bounce che arrivano più tardi come email finiscono nella casella mittente, non in Inbixio, quindi controlla anche quella inbox.

La soluzione si trova quasi sempre in Email Servers (server email) o presso il tuo provider di posta. Impostazioni SMTP spiegate copre i casi più comuni.

Cosa monitorare in produzione

La dashboard di Inbixio ti offre l’essenziale:

• Email Sent (email inviate) e la percentuale Failed Deliveries degli ultimi 7 giorni, ciascuna con la variazione rispetto ai 7 giorni precedenti.
• Avg Latency (latenza media): quanto tempo impiega il tuo server SMTP ad accettare le email. Un aumento improvviso spesso precede i fallimenti.
• Grafici del volume di chiamate API e di email sull’intero anno, per individuare tendenze e picchi stagionali.
• Logs (log) di ogni chiamata API: ID evento, endpoint, metodo, codice di stato, tempo di risposta e timestamp.

Dal tuo lato, traccia il numero di risposte diverse da 200 per codice di stato e imposta un avviso quando compaiono 401, 402 o il 429 del limite mensile. Significano che tutte le email si sono fermate, e i tuoi utenti se ne accorgeranno prima dei tuoi log.

Checklist

• Considera 200 come “in coda”; verifica i risultati del recapito nella dashboard
• Leggi sia error sia detail dalle risposte di errore
• Ritenta solo errori di rete, timeout, 5xx, 503 e il 429 del rate limit, rispettando Retry-After
• Imposta avvisi su 401, 402 e sul 429 del limite mensile
• Tieni d’occhio la scheda Usage Limit prima di lanci e importazioni
• Monitora la percentuale Failed Deliveries e correggi subito le impostazioni SMTP