Référence de l'API

Une API JSON sur HTTPS. 32 points de terminaison, tous versionnés sous /v1. Dernière mise à jour 1 novembre 2026.

• Authentification
• Erreurs
• Idempotence
• Limites
• Envoi
• État des messages
• Suppressions
• Webhooks
• Domaines d'envoi
• Statistiques et compte
• Équipe
• Bac à sable

Authentification

Chaque requête porte une clé d'API comme jeton bearer. Les clés sont créées sous Clés d'API et affichées une seule fois.

Authorization: Bearer zm_live_...

Une clé porte un ensemble de portées; une requête hors de celles-ci est refusée par un 403 insufficient_scope qui nomme la portée attendue.

Erreurs

Une erreur est du JSON avec un code machine stable et une phrase pour un humain. Faites correspondre sur error; message peut être reformulé ou traduit.

{
  "error": "insufficient_scope",
  "message": "This API key lacks the email:messages.send scope."
}

Les codes possibles sur un 422 comprennent invalid_from, invalid_email, invalid_domain, invalid_url, subject_too_long, body_too_large, file_too_large, reserved_header, too_many_headers et duplicate_header. Quelques validations plus anciennes retournent error sous forme de phrase sans code; traitez une valeur error non reconnue comme un refus à ne pas réessayer tel quel.

Idempotence

Envoyez un en-tête Idempotency-Key et une nouvelle tentative de la même requête n'enverra pas un second message. Les clés sont mémorisées pendant 24 heures.

Idempotency-Key: order-18472-receipt

C'est une protection contre le double envoi, non un cache de réponses : une requête qui arrive pendant que la première est encore en vol est refusée plutôt que servie depuis un envoi inachevé.

Limites

Envoi

Une adresse par requête. Un 2xx signifie que nous avons accepté le message et en avons pris la responsabilité, non qu'il est arrivé — interrogez le message ou prenez un webhook pour cela.

Champs de la requête

L'adresse from est définie sur la clé, non dans la requête : une clé divulguée ne peut donc pas envoyer au nom d'un autre.

# Envoyer un message
curl -X POST https://zedmail.com/v1/email/send \
  -H "Authorization: Bearer $ZEDMAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-18472-receipt" \
  -d '{
    "to": "jane@example.com",
    "subject": "Your receipt",
    "html": "<p>Thank you.</p>",
    "tags": ["receipt"]
  }'

=> 200
{ "status": "queued", "message_id": "msg_4f68af67910b67a097" }

État des messages

/v1/email/{id} répond à « qu'est-il arrivé à ce message ». /v1/recipients/{email} répond à « cette personne l'a-t-elle reçu », ce que le premier ne peut pas, car celui qui demande a rarement un identifiant de message.

États

Seuls les quatre derniers sont définitifs. blocked est celui qu'on oublie : le message n'a pas été envoyé parce que le chiffrement du transport n'a pu être établi, donc l'adresse reste bonne.

Suppressions

Une adresse supprimée est refusée avant toute tentative d'envoi. Les raisons sont bounce, complaint, unsubscribe, manual et soft_bounce_threshold. Un message blocked ne crée jamais de suppression — l'adresse reste valide.

Webhooks

Ces routes gèrent les points de terminaison. Les charges utiles, le schéma de signature et le calendrier des nouvelles tentatives sont documentés sur la page Webhooks de votre compte, où les exemples peuvent nommer vos propres points de terminaison et votre secret.

Domaines d'envoi

Vous ne pouvez envoyer que depuis un domaine que vous avez vérifié. La vérification contrôle DKIM, SPF et DMARC comme un destinataire les lit.

Statistiques et compte

Les paramètres from et to acceptent AAAA-MM-JJ. Les trois routes /v1/account/* reprennent la forme de leurs équivalents chez Amazon SES, pour qu'une migration conserve ses appels existants.

Équipe

Invitations et membres. Les routes /invites sont déclarées avant /{id} et les identifiants sont contraints en UUID, de sorte que le segment littéral invites ne peut jamais être lu comme un identifiant d'utilisateur.

Bac à sable

Un nouveau compte n'envoie qu'aux adresses qu'il a vérifiées. Ceci en ajoute une.

Ailleurs

• Charges utiles des webhooks, vérification de signature et calendrier des nouvelles tentatives
• FAQ  ·  Entente de traitement des données  ·  Journal des modifications
• /mcp — une enveloppe JSON-RPC sur ces points de terminaison pour les agents, filtrée par les mêmes portées.

Quelque chose manque ou est inexact ici ? Dites-le-nous et ce sera corrigé — cette page est vérifiée contre le routeur à chaque déploiement, mais seul le code dit ce qu'il fait.