POST /mailing/send
Mette in coda una nuova richiesta di email per la consegna.
Panoramica
Usa questo endpoint per inviare una singola richiesta di email a Mailiqo. La richiesta viene validata, i destinatari vengono elaborati e il messaggio viene messo in coda per la consegna asincrona.
La risposta è incapsulata e può restituire tre stati logici:
status = success: tutti i destinatari sono stati accettati.status = warning: alcuni destinatari sono stati accettati e altri rifiutati.status = error: nessun destinatario è stato accettato, oppure si è verificata un'altra condizione di validazione/errore.
Endpoint
POST /v1/mailing/sendcurl -X POST https://api.mailiqo.com/v1/mailing/send \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Benvenuta in Mailiqo",
"body_html": "<p>Ciao mondo</p>"
}'Corpo della richiesta
Il corpo della richiesta va inviato in JSON.
Campi obbligatori
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
from | string (email) | Sì | Indirizzo email del mittente. |
subject | string | Sì | Oggetto dell'email. |
to | mixed | Sì | Destinatari principali. Vedi il formato dei destinatari qui sotto. |
body_html o body_txt | string | Sì | Almeno uno dei due è obbligatorio. Contenuto del corpo dell'email. |
Campi facoltativi
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
body_html | string | No | Contenuto del corpo in HTML. |
body_txt | string | No | Contenuto del corpo in testo semplice. |
cc | mixed | No | Destinatari in copia. Vedi il formato dei destinatari qui sotto. |
bcc | mixed | No | Destinatari in copia nascosta. Vedi il formato dei destinatari qui sotto. |
attachments | array | No | Lista di allegati. |
force_validation | boolean | No | Esegue un nuovo controllo su ogni destinatario durante l'invio, senza riutilizzare risultati precedenti. Equivale a validation.mode: "always", e spende un credito per destinatario controllato |
validation | object | No | Regola la validazione solo per questo invio. Vedi Validazione per questo invio |
Validazione per questo invio
Per impostazione predefinita si applica la configurazione di validazione del dominio di invio. Se questo invio richiede più attenzione — una conferma d'ordine, una reimpostazione della password — aggiungi l'oggetto validation:
{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Conferma il tuo ordine",
"body_html": "<p>Grazie per il tuo acquisto.</p>",
"validation": {
"mode": "always",
"level": "restrictive",
"block": ["catch_all", "risky"]
}
}| Campo | Valori | Descrizione |
|---|---|---|
mode | unknown_only, always | Quando viene sondata la casella del destinatario |
level | preventive, restrictive | Quanto è esigente il controllo |
block | lista di catch_all, risky, unknown | Risultati dubbi che scarti per questo invio |
Un invio può solo rendere più rigoroso
La regolazione non allenta mai la configurazione del dominio: se il dominio sonda già a ogni invio, chiedere unknown_only non lo abbassa, e block si aggiunge soltanto a ciò che il dominio già blocca. Per questo mode non accetta never.
Un valore non riconosciuto restituisce 400 con il codice 1419.
Tutti e tre i campi, come corrispondono alla configurazione del dominio e come leggere il risultato per destinatario sono spiegati in Validazione dei destinatari.
Formato dei destinatari
⚠️ Attenzione: sono consentiti al massimo 50 destinatari validi in una singola richiesta. Se dopo la pre-elaborazione vengono accettati più di 50 destinatari, la richiesta viene rifiutata.
to, cc e bcc accettano i seguenti formati:
"[email protected]"[
"[email protected]",
"[email protected]"
]{
"name": "John Doe",
"email": "[email protected]"
}[
{
"name": "John Doe",
"email": "[email protected]"
},
{
"name": "Jane Doe",
"email": "[email protected]"
}
]Formato degli allegati
Ogni allegato supporta i seguenti campi:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
filename | string | Sì | Nome del file. |
content_base64 | string | Sì | Contenuto del file codificato in base64. |
content_type | string | No | Tipo MIME del file. |
Esempio di richiesta
{
"from": "[email protected]",
"subject": "Benvenuta in Mailiqo",
"body_html": "<p>Ciao mondo</p>",
"body_txt": "Ciao mondo",
"to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"cc": [
"[email protected]",
"invalid@example"
],
"bcc": [],
"attachments": [
{
"filename": "invoice.pdf",
"content_base64": "JVBERi0xLjQKJ...",
"content_type": "application/pdf"
}
]
}Esempio di risposta riuscita (status = warning)
Succede quando almeno un destinatario viene accettato e almeno uno viene rifiutato.
{
"status": "warning",
"data": {
"uuid": "0c4ab8dc-0df4-4ef6-89ea-53ee4a8e1a3f",
"sent_to": [
{
"name": "Jane Doe",
"email": "[email protected]"
},
{
"email": "[email protected]",
"name": null
}
],
"rejected_recipients": [
{
"email": "invalid@example",
"name": null,
"reason": "invalid_format"
}
]
}
}Esempio di risposta riuscita (status = success)
Succede quando tutti i destinatari vengono accettati.
{
"status": "success",
"data": {
"uuid": "0c4ab8dc-0df4-4ef6-89ea-53ee4a8e1a3f",
"sent_to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"rejected_recipients": []
}
}Esempio di risposta di errore (status = error)
Quando nessun destinatario può essere accettato, l'endpoint restituisce 400 e include i destinatari rifiutati dentro error.details.
{
"status": "error",
"error": {
"code": "1412",
"message": "No valid recipients found.",
"details": {
"sent_to": [],
"rejected_recipients": [
{
"email": "invalid@example",
"name": null,
"reason": "invalid_format"
}
]
}
}
}Campi della risposta
Wrapper di success/warning
| Campo | Tipo | Descrizione |
|---|---|---|
status | string | success o warning |
data.uuid | string | UUID generato per la richiesta di email messa in coda |
data.sent_to | array | Lista dei destinatari accettati |
data.rejected_recipients | array | Lista dei destinatari rifiutati con il motivo del rifiuto |
Email aggiuntive
Quando la quota mensile inclusa nel tuo piano si esaurisce, l'invio viene rifiutato con l'errore 1417. Se attivi le email aggiuntive dal pannello, l'invio continua oltre la quota fino al limite che hai impostato; quando quel limite viene raggiunto viene rifiutato con 1418, e l'eccedenza usata viene addebitata nella fattura successiva.
Oggetto destinatario rifiutato
| Campo | Tipo | Descrizione |
|---|---|---|
email | string | Indirizzo email rifiutato |
name | string/null | Nome del destinatario, se fornito |
reason | string | Motivo del rifiuto leggibile dalla macchina |
Wrapper di errore
| Campo | Tipo | Descrizione |
|---|---|---|
status | string | Sempre error |
error.code | string | Codice di errore dell'API |
error.message | string | Messaggio di errore tradotto |
error.details.sent_to | array | Sempre vuoto quando nessun destinatario è stato accettato |
error.details.rejected_recipients | array | Destinatari rifiutati con il motivo del rifiuto |
Risposte HTTP
| Stato | Significato |
|---|---|
200 | Richiesta elaborata. Se tutti i destinatari sono stati accettati, il wrapper restituisce status=success; se alcuni sono stati rifiutati, restituisce status=warning. |
400 | Richiesta non valida o errore di validazione. Se nessun destinatario è valido, viene restituito error.details.rejected_recipients. |
401 | Autenticazione fallita o richiesta non autorizzata. |
429 | Limite di invio raggiunto (1421). Aspetta i secondi indicati nell'header Retry-After prima di inviare di nuovo. Vedi Limiti di invio. |
500 | Errore interno del server. |
Note
- La consegna è asincrona dopo l'accettazione della richiesta.
- I destinatari accettati possono differire da quelli inviati se alcuni indirizzi vengono rifiutati durante la pre-elaborazione.
body_htmlebody_txtsono supportati nella stessa richiesta.- I destinatari rifiutati vengono registrati anche singolarmente con il loro motivo di rifiuto nei log visibili al cliente.
Endpoint correlati
POST /mailing/send-template— invia usando un templateGET /mailing/email-request/{uuid}— stato della richiestaGET /mailing/email-message/{uuid}— stato e validazione per destinatario
Vedi anche
- API di invio email — il flusso completo e gli stati della risposta
- Validazione dei destinatari — come si configura e cosa viene controllato
- API di validazione email — controlla indirizzi senza inviare nulla
