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
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": "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
| Champ | Type | Requis | Description |
|---|---|---|---|
from | string (email) | Oui | Adresse email de l'expéditeur. |
subject | string | Oui | Objet de l'email. |
to | mixed | Oui | Destinataires principaux. Voir le format des destinataires ci-dessous. |
body_html ou body_txt | string | Oui | Au moins l'un des deux est requis. Contenu du corps de l'email. |
Champs facultatifs
| Champ | Type | Requis | Description |
|---|---|---|---|
body_html | string | Non | Contenu HTML du corps. |
body_txt | string | Non | Contenu texte brut du corps. |
cc | mixed | Non | Destinataires en copie. Voir le format des destinataires ci-dessous. |
bcc | mixed | Non | Destinataires en copie cachée. Voir le format des destinataires ci-dessous. |
attachments | array | Non | Liste des pièces jointes. |
force_validation | boolean | Non | Lance 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é |
validation | object | Non | Ajuste 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 :
{
"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"]
}
}| Champ | Valeurs | Description |
|---|---|---|
mode | unknown_only, always | Quand la boîte mail du destinataire est sondée |
level | preventive, restrictive | Niveau d'exigence de la vérification |
block | liste parmi catch_all, risky, unknown | Ré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 :
"[email protected]"[
"[email protected]",
"[email protected]"
]{
"name": "John Doe",
"email": "[email protected]"
}[
{
"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 :
| Champ | Type | Requis | Description |
|---|---|---|---|
filename | string | Oui | Nom du fichier. |
content_base64 | string | Oui | Contenu du fichier encodé en base64. |
content_type | string | Non | Type MIME du fichier. |
Exemple de requête
{
"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é.
{
"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.
{
"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.
{
"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
| Champ | Type | Description |
|---|---|---|
status | string | success ou warning |
data.uuid | string | UUID généré pour la demande d'envoi mise en file |
data.sent_to | array | Liste des destinataires acceptés |
data.rejected_recipients | array | Liste 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é
| Champ | Type | Description |
|---|---|---|
email | string | Adresse email rejetée |
name | string/null | Nom du destinataire s'il a été fourni |
reason | string | Motif de rejet lisible par machine |
Enveloppe d'erreur
| Champ | Type | Description |
|---|---|---|
status | string | Toujours error |
error.code | string | Code d'erreur de l'API |
error.message | string | Message d'erreur traduit |
error.details.sent_to | array | Toujours vide quand aucun destinataire n'a été accepté |
error.details.rejected_recipients | array | Destinataires rejetés avec le motif du rejet |
Réponses HTTP
| Statut | Signification |
|---|---|
200 | Requê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. |
400 | Requête invalide ou erreur de validation. Si aucun destinataire n'est valide, error.details.rejected_recipients est renvoyé. |
401 | Authentification échouée ou requête non autorisée. |
429 | Limite d'envoi atteinte (1421). Attendez le nombre de secondes indiqué dans l'en-tête Retry-After avant de renvoyer. Voir Limites d'envoi. |
500 | Erreur 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_htmletbody_txtsont 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
POST /mailing/send-template— envoyer à partir d'un modèleGET /mailing/email-request/{uuid}— statut de la demandeGET /mailing/email-message/{uuid}— statut et validation par destinataire
Voir aussi
- API d'envoi d'emails — le flux complet et les états de réponse
- Validation des destinataires — comment elle se configure et ce qui est vérifié
- API de validation d'emails — vérifier des adresses sans rien leur envoyer
