Skip to content

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 ​

http
POST /v1/mailing/send
bash
curl -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 ​

CampoTipoObbligatorioDescrizione
fromstring (email)SìIndirizzo email del mittente.
subjectstringSìOggetto dell'email.
tomixedSìDestinatari principali. Vedi il formato dei destinatari qui sotto.
body_html o body_txtstringSìAlmeno uno dei due è obbligatorio. Contenuto del corpo dell'email.

Campi facoltativi ​

CampoTipoObbligatorioDescrizione
body_htmlstringNoContenuto del corpo in HTML.
body_txtstringNoContenuto del corpo in testo semplice.
ccmixedNoDestinatari in copia. Vedi il formato dei destinatari qui sotto.
bccmixedNoDestinatari in copia nascosta. Vedi il formato dei destinatari qui sotto.
attachmentsarrayNoLista di allegati.
force_validationbooleanNoEsegue 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
validationobjectNoRegola 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:

json
{
  "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"]
  }
}
CampoValoriDescrizione
modeunknown_only, alwaysQuando viene sondata la casella del destinatario
levelpreventive, restrictiveQuanto è esigente il controllo
blocklista di catch_all, risky, unknownRisultati 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:

json
{
  "name": "John Doe",
  "email": "[email protected]"
}
json
[
  {
    "name": "John Doe",
    "email": "[email protected]"
  },
  {
    "name": "Jane Doe",
    "email": "[email protected]"
  }
]

Formato degli allegati ​

Ogni allegato supporta i seguenti campi:

CampoTipoObbligatorioDescrizione
filenamestringSìNome del file.
content_base64stringSìContenuto del file codificato in base64.
content_typestringNoTipo MIME del file.

Esempio di richiesta ​

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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 ​

CampoTipoDescrizione
statusstringsuccess o warning
data.uuidstringUUID generato per la richiesta di email messa in coda
data.sent_toarrayLista dei destinatari accettati
data.rejected_recipientsarrayLista 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 ​

CampoTipoDescrizione
emailstringIndirizzo email rifiutato
namestring/nullNome del destinatario, se fornito
reasonstringMotivo del rifiuto leggibile dalla macchina

Wrapper di errore ​

CampoTipoDescrizione
statusstringSempre error
error.codestringCodice di errore dell'API
error.messagestringMessaggio di errore tradotto
error.details.sent_toarraySempre vuoto quando nessun destinatario è stato accettato
error.details.rejected_recipientsarrayDestinatari rifiutati con il motivo del rifiuto

Risposte HTTP ​

StatoSignificato
200Richiesta elaborata. Se tutti i destinatari sono stati accettati, il wrapper restituisce status=success; se alcuni sono stati rifiutati, restituisce status=warning.
400Richiesta non valida o errore di validazione. Se nessun destinatario è valido, viene restituito error.details.rejected_recipients.
401Autenticazione fallita o richiesta non autorizzata.
429Limite di invio raggiunto (1421). Aspetta i secondi indicati nell'header Retry-After prima di inviare di nuovo. Vedi Limiti di invio.
500Errore 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_html e body_txt sono supportati nella stessa richiesta.
  • I destinatari rifiutati vengono registrati anche singolarmente con il loro motivo di rifiuto nei log visibili al cliente.

Endpoint correlati ​

Vedi anche ​

Built with VitePress