Envoyer un e-mail

Ce guide détaille chaque partie d’une requête POST /emails et ce qu’Emailit en fait, de l’adresse d’expéditeur jusqu’aux erreurs que vous pouvez recevoir. Pour la référence complète des paramètres, consultez Envoyer un e-mail dans la référence de l’API.

Avant de commencer

• Un domaine d’envoi vérifié dans votre espace de travail. Consultez Ajouter un domaine.
• Une clé API de portée Full Access ou Sending Only. Consultez Clés API.
• L’accès production si vous envoyez à d’autres personnes que les membres de votre espace de travail. Consultez Accès production.
• Assez de crédits pour chaque destinataire (1 crédit chacun).

Envoyer un e-mail simple

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);

Définir l’adresse d’expéditeur

from est obligatoire et accepte une adresse sous l’une de ces formes :

• billing@acme.com
• Acme Billing <billing@acme.com>, ou avec des guillemets, "Acme, Inc." <billing@acme.com>

Le domaine après le @ doit être un domaine d’envoi vérifié du même espace de travail :

• La correspondance est exacte. La comparaison ignore la casse, mais mail.acme.com et acme.com sont des domaines différents. Ajoutez et vérifiez chaque sous-domaine depuis lequel vous envoyez.
• N’importe quelle partie locale convient. Vous n’avez pas besoin d’une boîte aux lettres pour billing@ ou no-reply@.
• Les domaines en attente ne peuvent pas envoyer. Un domaine encore en attente d’examen (Pending verification) est traité comme non vérifié.
• Les clés restreintes restent sur leur domaine. Une clé Sending Only restreinte à un domaine ne peut envoyer que depuis ce domaine.
• Les domaines en pause sont bloqués. Si la santé d’envoi a mis le domaine en pause, les envois depuis ce domaine sont rejetés jusqu’à la levée de la pause.

Ajouter des destinataires

to est obligatoire. cc et bcc sont facultatifs. Chaque champ accepte une chaîne ou un tableau de chaînes, avec ou sans nom d’affichage, et contient 50 adresses au maximum. Une chaîne peut contenir plusieurs adresses séparées par des virgules ; utilisez un tableau quand un nom d’affichage contient lui-même une virgule.

Emailit supprime les doublons entre to, cc et bcc (sans tenir compte de la casse), puis crée un e-mail par destinataire unique, chacun avec son propre ID em_. Chaque copie porte les mêmes en-têtes To et Cc, si bien que les destinataires voient la conversation comme d’habitude, et les destinataires Bcc n’apparaissent jamais dans les en-têtes d’une copie.

Quand une requête a plus d’un destinataire, la réponse inclut un objet ids qui associe chaque destinataire à l’ID de son e-mail. id est l’e-mail du premier destinataire.

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}

Chaque destinataire coûte 1 crédit et compte dans vos limites de débit. Un destinataire faisant l’objet d’un blocage de type recipient est accepté, puis marqué suppressed au lieu d’être livré.

Rédiger le contenu

Si reply_to indique la même adresse que from, Emailit supprime l’en-tête Reply-To, car il n’apporte rien et certains filtres anti-spam le pénalisent.

Envoyer avec un modèle

Renseignez dans template l’alias d’un modèle ou un ID tem_, et transmettez variables pour les variables Temple qu’il contient.

• Un alias envoie la version actuellement publiée pour cet alias. Si aucune version n’est publiée, la requête échoue avec 404.
• Un ID tem_ envoie cette version précise, publiée ou non. Utilisez-le pour tester une version brouillon avant de la publier.

Les champs de la requête ont priorité sur le modèle : un subject, un html ou un text que vous envoyez remplace la valeur du modèle. Si vous n’envoyez pas reply_to, l’adresse de réponse (Reply-To) du modèle est utilisée. from est toujours obligatoire dans la requête. Pour comprendre le fonctionnement de la publication, consultez Versions de modèle.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);

variables fonctionne aussi sans modèle : Emailit effectue le rendu des variables Temple dans le subject, le html et le text que vous envoyez directement.

Gérer le suivi

Par défaut, chaque e-mail suit les paramètres Track loads et Track clicks de son domaine d’envoi. Remplacez-les pour un e-mail donné avec tracking :

• "tracking": true ou false active ou désactive à la fois le suivi des chargements (ouvertures) et celui des clics.
• "tracking": { "loads": true, "clicks": false } règle chacun séparément.

Le suivi ne fonctionne que si le CNAME de suivi du domaine est vérifié. Sans lui, l’e-mail est envoyé sans suivi et la requête réussit quand même. L’objet tracking de la réponse indique les paramètres réellement appliqués. Consultez Suivi des ouvertures et des clics.

Ajouter des en-têtes et des métadonnées

Utilisez headers pour les en-têtes d’e-mail personnalisés, comme List-Unsubscribe, et meta pour vos propres paires clé-valeur de type chaîne. Emailit enregistre meta avec l’e-mail et l’inclut dans les événements webhook. Consultez En-têtes et métadonnées.

Pour joindre des fichiers, programmer l’envoi ou sécuriser les relances, consultez Pièces jointes, Programmation et Idempotence.

Lire la réponse

Une requête réussie renvoie 200 :

Conservez l’id (ou l’objet ids) pour faire correspondre les futurs événements webhook et retrouver l’e-mail avec Récupérer un e-mail.

Événements

L’e-mail de chaque destinataire émet ses propres événements :

1. email.accepted juste après la requête, ou email.scheduled s’il a une heure d’envoi future.
2. Des événements de livraison à mesure que l’e-mail progresse dans la chaîne de traitement : email.delivered, email.attempted (échec temporaire, Emailit réessaiera), email.bounced, email.failed, email.rejected ou email.suppressed. Un e-mail retenu pour examen émet email.held.
3. Des événements d’engagement, si le suivi est activé : email.loaded et email.clicked. Les signalements comme spam émettent email.complained.

Pour la signification de chaque statut, consultez Statuts des e-mails.

Erreurs

Les erreurs de validation renvoient la liste de tous les problèmes détectés :

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}

Un espace de travail suspendu reçoit 403 avec Workspace is suspended à chaque envoi. Pour le format général des erreurs, consultez Erreurs.

Voir aussi

• Envoyer un e-mail dans la référence de l’API
• Modèles
• Statuts des e-mails
• Types d’événements webhook
• Pourquoi mon e-mail n’est-il pas arrivé ?