Skip to content

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 ​

EndpointCosa fa
POST /v1/mailing/sendMette in coda un invio con il contenuto nella richiesta
POST /v1/mailing/send-templateMette 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 destinatario

Una 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:

statusHTTPSignificato
success200Tutti i destinatari sono stati accettati
warning200Alcuni accettati e alcuni rifiutati; controlla rejected_recipients
error400Nessun 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:

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:

CodiceSignificato
1412Nessun destinatario valido trovato
1413Più di 50 destinatari validi in una richiesta
1417Quota mensile di email esaurita
1418Limite di email aggiuntive raggiunto
1419Opzioni di validazione non valide
1421Limite di invio orario o giornaliero raggiunto (HTTP 429). Vedi Limiti di invio
1422Il messaggio da solo supera il limite di invio orario o giornaliero (HTTP 400). Dividilo in messaggi più piccoli

Built with VitePress