Envoyer un email par API REST avec votre boîte SMTP

Mis à jour le 12 octobre 2026

Un envoi est un POST /v1/messages authentifié avec une clé API. Le seul champ obligatoire est mailbox_id : c’est la boîte qui envoie.

curl https://smapiz.com/v1/messages \
  -H "Authorization: Bearer smz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_...",
    "to": "Ada <[email protected]>",
    "cc": ["[email protected]"],
    "subject": "Votre commande",
    "html": "<p>Votre commande est expédiée.</p>",
    "text": "Votre commande est expédiée."
  }'

La réponse contient le message avec son id (msg_…) et son statut. L’envoi SMTP se fait ensuite en arrière-plan, avec de nouvelles tentatives en cas d’échec temporaire.

Les champs utiles

to, cc, bcc, reply_to : une adresse, "Nom <adresse>", ou une liste.
html et/ou text : le contenu, ou un template_id (voir les templates).
from_name : remplace le nom d’expéditeur de la boîte pour cet envoi.
headers : en-têtes personnalisés.
tags et metadata : vos propres valeurs, renvoyées dans les webhooks (pratique pour retrouver une commande ou un client).

Pièces jointes

Le contenu est encodé en base64. Ajoutez content_id pour afficher une image dans le HTML avec cid:.

"attachments": [
  { "filename": "facture.pdf", "content": "JVBERi0xLjQK..." },
  { "filename": "logo.png", "content": "iVBORw0KGgo...", "content_id": "logo" }
],
"html": "<img src=\"cid:logo\"> <p>Votre facture est jointe.</p>"

Éviter les doublons

Envoyez un en-tête Idempotency-Key (par exemple l’identifiant de la commande). Si la requête est rejouée avec la même clé, l’email n’est pas renvoyé une seconde fois.

-H "Idempotency-Key: commande-1042"

Programmer un envoi

Ajoutez send_at au format ISO 8601, jusqu’à 30 jours à l’avance. Pour annuler avant l’heure : POST /v1/messages/{id}/cancel, ou le bouton Annuler l’envoi programmé dans Messages.

"send_at": "2026-11-02T09:00:00+01:00"

Suivre le résultat

L’onglet Messages montre chaque envoi, son statut et la réponse du serveur SMTP. Côté code, abonnez un webhook à message.sent, message.failed et message.bounced (adresse inexistante, boîte pleine…).

On peut aussi envoyer à la main depuis Messages > Nouveau message, utile pour tester une boîte.