POST /mailing/send-template
Mette in coda una nuova richiesta di email usando un template esistente.
Panoramica
Usa questo endpoint per inviare un'email con un template salvato in Mailiqo. La versione del template selezionata per l'invio fornisce l'oggetto, il corpo HTML e il corpo in testo semplice. I destinatari vengono elaborati come in POST /mailing/send.
I segnaposto del template usano la sintassi . Le variabili non presenti vengono sostituite con una stringa vuota, e le variabili che non compaiono nel template vengono ignorate.
Endpoint
POST /v1/mailing/send-templatecurl -X POST https://api.mailiqo.com/v1/mailing/send-template \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template_uuid": "7e9c6c60-8a98-4c10-9d5e-xxxxxxxx",
"from": "[email protected]",
"to": "[email protected]",
"variables": {"first_name": "Jane"}
}'Corpo della richiesta
Il corpo della richiesta va inviato in JSON.
Campi obbligatori
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
template_uuid | string | Sì | UUID del template da usare. |
from | string (email) | Sì | Indirizzo email del mittente. |
to | mixed | Sì | Destinatari principali. Vedi il formato dei destinatari qui sotto. |
Campi facoltativi
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
cc | mixed | No | Destinatari in copia. |
bcc | mixed | No | Destinatari in copia nascosta. |
variables | object | No | Valori usati per sostituire i segnaposto del template. |
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
Funziona esattamente come in POST /mailing/send. Per impostazione predefinita si applica la configurazione del dominio di invio; l'oggetto validation la rende più rigorosa solo per questa richiesta:
{
"template_uuid": "7e9c6c60-8a98-4c10-9d5e-xxxxxxxx",
"from": "[email protected]",
"to": "[email protected]",
"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, 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.
La spiegazione completa è in Validazione dei destinatari.
Formato dei destinatari
to, cc e bcc usano gli stessi formati documentati in POST /mailing/send.
Formato delle variabili
{
"first_name": "Jane",
"company_name": "Acme"
}Questi valori possono essere usati da segnaposto come {{first_name}} e {{company_name}}.
Esempio di richiesta
{
"template_uuid": "7e9c6c60-8a98-4c10-9d5e-xxxxxxxx",
"from": "[email protected]",
"to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"variables": {
"first_name": "Jane",
"company_name": "Acme"
},
"attachments": [
{
"filename": "invoice.pdf",
"content_base64": "JVBERi0xLjQKJ...",
"content_type": "application/pdf"
}
]
}Esempio di risposta riuscita (status = success)
{
"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",
"error": {
"code": "1416",
"message": "Email template not found.",
"details": {}
}
}Risposte HTTP
| Stato | Significato |
|---|---|
200 | Richiesta elaborata. |
400 | Richiesta non valida o errore di validazione. |
401 | Autenticazione fallita o richiesta non autorizzata. |
404 | Template non trovato. |
409 | Il template non ha una versione pubblicata (1420). |
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
- Il template fornisce l'oggetto e il contenuto del corpo.
- La consegna è asincrona dopo l'accettazione della richiesta.
- I destinatari accettati e rifiutati seguono lo stesso formato di risposta di
POST /mailing/send.
Endpoint correlati
POST /mailing/send— invia senza 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
