API di invio email
Metti in coda le email e segui la loro consegna destinatario per destinatario. Ci sono due modi di inviare — con il contenuto nella richiesta stessa, oppure con un template salvato — e due endpoint di consultazione per sapere cosa è successo dopo.
Ogni richiesta usa l'header X-API-KEY. Vedi Autenticazione.
Endpoint
| Endpoint | Cosa fa |
|---|---|
POST /v1/mailing/send | Mette in coda un invio con il contenuto nella richiesta |
POST /v1/mailing/send-template | Mette in coda un invio usando un template salvato |
GET /v1/mailing/email-request/{uuid} | Stato della richiesta e messaggi che ha generato |
GET /v1/mailing/email-message/{uuid} | Stato di consegna e validazione per un destinatario |
L'invio è asincrono
L'API accetta la richiesta e la mette in coda; non consegna sul momento. Per questo una richiesta riuscita non significa ancora una consegna riuscita, e il tracciamento richiede due passaggi:
POST /v1/mailing/send -> uuid della richiesta
GET /v1/mailing/email-request/{uuid} -> email_messages[] (un uuid per destinatario)
GET /v1/mailing/email-message/{uuid} -> stato e validazione di quel destinatarioUna richiesta (email_request) genera un messaggio per destinatario (email_message). Stato di consegna, aperture, clic e risultato della validazione stanno sul messaggio, non sulla richiesta.
I tre stati della risposta
Entrambi gli endpoint di invio restituiscono una risposta incapsulata, che può risolversi in tre modi a seconda di quanti destinatari sono stati accettati:
status | HTTP | Significato |
|---|---|---|
success | 200 | Tutti i destinatari sono stati accettati |
warning | 200 | Alcuni accettati e alcuni rifiutati; controlla rejected_recipients |
error | 400 | Nessun destinatario è stato accettato, oppure la richiesta non era valida |
Controlla sempre rejected_recipients
Un 200 non garantisce che tutti i tuoi destinatari siano passati. Con status = warning la richiesta viene messa in coda solo per quelli accettati, e quelli scartati tornano con il loro motivo in data.rejected_recipients. Quando nessuno viene accettato, la stessa lista arriva in error.details.rejected_recipients.
Destinatari
to, cc e bcc accettano gli stessi quattro formati (un singolo indirizzo, una lista, un oggetto con nome, o una lista di oggetti), documentati in Formato dei destinatari.
Sono consentiti al massimo 50 destinatari validi per richiesta. Se dopo la pre-elaborazione ne vengono accettati più di 50, la richiesta viene rifiutata.
Validazione dei destinatari
Prima di consegnare, Mailiqo controlla che ogni destinatario esista e sia raggiungibile. Si configura per dominio, e qualsiasi invio può renderla più rigorosa con l'oggetto validation:
- Validazione per questo invio — il parametro, con un esempio
- Validazione dei destinatari — cosa viene controllato e come si configura
- API di validazione email — controlla indirizzi senza inviare nulla
Il risultato per destinatario non torna nella risposta dell'invio: il controllo avanzato avviene dopo che hai ricevuto la risposta. Lo leggi nel blocco validation di GET /email-message/{uuid}.
Errori
I codici di invio vanno da 1400 a 1422 e sono elencati nel riferimento degli errori. I più comuni:
| Codice | Significato |
|---|---|
1412 | Nessun destinatario valido trovato |
1413 | Più di 50 destinatari validi in una richiesta |
1417 | Quota mensile di email esaurita |
1418 | Limite di email aggiuntive raggiunto |
1419 | Opzioni di validazione non valide |
1421 | Limite di invio orario o giornaliero raggiunto (HTTP 429). Vedi Limiti di invio |
1422 | Il messaggio da solo supera il limite di invio orario o giornaliero (HTTP 400). Dividilo in messaggi più piccoli |
