Skip to content

POST /mailing/send ​

Mettez en file une nouvelle demande d'envoi d'email.

Vue d'ensemble ​

Utilisez cet endpoint pour soumettre une demande d'envoi unique à Mailiqo. La requête est validée, les destinataires sont traités et le message est mis en file pour une livraison asynchrone.

La réponse est enveloppée et peut renvoyer trois états logiques :

  • status = success : tous les destinataires ont été acceptés.
  • status = warning : certains destinataires ont été acceptés et d'autres rejetés.
  • status = error : aucun destinataire n'a pu être accepté, ou une autre condition de validation/erreur s'est produite.

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": "Bienvenue chez Mailiqo",
    "body_html": "<p>Bonjour le monde</p>"
  }'

Corps de la requête ​

Le corps de la requête doit être envoyé en JSON.

Champs obligatoires ​

ChampTypeRequisDescription
fromstring (email)OuiAdresse email de l'expéditeur.
subjectstringOuiObjet de l'email.
tomixedOuiDestinataires principaux. Voir le format des destinataires ci-dessous.
body_html ou body_txtstringOuiAu moins l'un des deux est requis. Contenu du corps de l'email.

Champs facultatifs ​

ChampTypeRequisDescription
body_htmlstringNonContenu HTML du corps.
body_txtstringNonContenu texte brut du corps.
ccmixedNonDestinataires en copie. Voir le format des destinataires ci-dessous.
bccmixedNonDestinataires en copie cachée. Voir le format des destinataires ci-dessous.
attachmentsarrayNonListe des pièces jointes.
force_validationbooleanNonLance une nouvelle vérification de chaque destinataire pendant l'envoi, sans réutiliser les résultats précédents. Équivaut à validation.mode: "always", et consomme un crédit par destinataire vérifié
validationobjectNonAjuste la validation pour cet envoi seulement. Voir Validation pour cet envoi

Validation pour cet envoi ​

Par défaut, la configuration de validation du domaine d'envoi s'applique. Si cet envoi mérite plus d'attention — une confirmation de commande, une réinitialisation de mot de passe — ajoutez l'objet validation :

json
{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Confirmez votre commande",
  "body_html": "<p>Merci pour votre achat.</p>",
  "validation": {
    "mode": "always",
    "level": "restrictive",
    "block": ["catch_all", "risky"]
  }
}
ChampValeursDescription
modeunknown_only, alwaysQuand la boîte mail du destinataire est sondée
levelpreventive, restrictiveNiveau d'exigence de la vérification
blockliste parmi catch_all, risky, unknownRésultats douteux que vous écartez pour cet envoi

Un envoi ne peut que renforcer

L'ajustement n'assouplit jamais la configuration du domaine : si le domaine sonde déjà à chaque envoi, demander unknown_only ne l'abaisse pas, et block ne fait qu'ajouter à ce que le domaine bloque déjà. C'est pourquoi mode n'accepte pas never.

Une valeur non reconnue renvoie 400 avec le code 1419.

Les trois champs, leur correspondance avec la configuration du domaine et la lecture du résultat par destinataire sont couverts dans Validation des destinataires.

Format des destinataires ​

⚠️ Attention : un maximum de 50 destinataires valides est autorisé par requête. Si plus de 50 destinataires sont acceptés après prétraitement, la requête est rejetée.

to, cc et bcc acceptent les formats suivants :

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

Format des pièces jointes ​

Chaque pièce jointe prend en charge les champs suivants :

ChampTypeRequisDescription
filenamestringOuiNom du fichier.
content_base64stringOuiContenu du fichier encodé en base64.
content_typestringNonType MIME du fichier.

Exemple de requête ​

json
{
  "from": "[email protected]",
  "subject": "Bienvenue chez Mailiqo",
  "body_html": "<p>Bonjour le monde</p>",
  "body_txt": "Bonjour le monde",
  "to": [
    {
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  ],
  "cc": [
    "[email protected]",
    "invalid@example"
  ],
  "bcc": [],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content_base64": "JVBERi0xLjQKJ...",
      "content_type": "application/pdf"
    }
  ]
}

Exemple de réponse réussie (status = warning) ​

Cela se produit quand au moins un destinataire est accepté et au moins un est rejeté.

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"
      }
    ]
  }
}

Exemple de réponse réussie (status = success) ​

Cela se produit quand tous les destinataires sont acceptés.

json
{
  "status": "success",
  "data": {
    "uuid": "0c4ab8dc-0df4-4ef6-89ea-53ee4a8e1a3f",
    "sent_to": [
      {
        "name": "Jane Doe",
        "email": "[email protected]"
      }
    ],
    "rejected_recipients": []
  }
}

Exemple de réponse d'erreur (status = error) ​

Quand aucun destinataire ne peut être accepté, l'endpoint renvoie 400 et inclut les destinataires rejetés dans 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"
        }
      ]
    }
  }
}

Champs de la réponse ​

Enveloppe success/warning ​

ChampTypeDescription
statusstringsuccess ou warning
data.uuidstringUUID généré pour la demande d'envoi mise en file
data.sent_toarrayListe des destinataires acceptés
data.rejected_recipientsarrayListe des destinataires rejetés avec le motif du rejet

Emails supplémentaires

Une fois le quota mensuel inclus dans votre plan épuisé, l'envoi est rejeté avec l'erreur 1417. Si vous activez les emails supplémentaires depuis l'espace client, l'envoi continue au-delà du quota jusqu'au plafond que vous fixez ; quand ce plafond est atteint, il est rejeté avec 1418, et le dépassement utilisé est facturé sur votre prochaine facture.

Objet destinataire rejeté ​

ChampTypeDescription
emailstringAdresse email rejetée
namestring/nullNom du destinataire s'il a été fourni
reasonstringMotif de rejet lisible par machine

Enveloppe d'erreur ​

ChampTypeDescription
statusstringToujours error
error.codestringCode d'erreur de l'API
error.messagestringMessage d'erreur traduit
error.details.sent_toarrayToujours vide quand aucun destinataire n'a été accepté
error.details.rejected_recipientsarrayDestinataires rejetés avec le motif du rejet

Réponses HTTP ​

StatutSignification
200Requête traitée. Si tous les destinataires ont été acceptés, l'enveloppe renvoie status=success ; si certains ont été rejetés, elle renvoie status=warning.
400Requête invalide ou erreur de validation. Si aucun destinataire n'est valide, error.details.rejected_recipients est renvoyé.
401Authentification échouée ou requête non autorisée.
429Limite d'envoi atteinte (1421). Attendez le nombre de secondes indiqué dans l'en-tête Retry-After avant de renvoyer. Voir Limites d'envoi.
500Erreur interne du serveur.

Remarques ​

  • La livraison est asynchrone une fois la requête acceptée.
  • Les destinataires acceptés peuvent différer des destinataires soumis si certaines adresses sont rejetées pendant le prétraitement.
  • body_html et body_txt sont tous deux pris en charge dans la même requête.
  • Les destinataires rejetés sont aussi journalisés individuellement avec leur motif de rejet dans les journaux visibles par le client.

Endpoints associés ​

Voir aussi ​

Built with VitePress