Plumail.
Se connecterCréer un compte gratuit

Langue

Se connecterCréer un compte gratuit
Guide d'installation

Brancher Plumail dans votre application

L'API REST remplace un service d'envoi transactionnel. Les champs et la réponse sont ceux de Resend : une migration se résume à l'adresse de base et à la clé.

  1. Créer une clé d'API

    Dans votre espace Plumail : Réglages → API → Nouvelle clé. Nommez-la, cochez les droits, validez. La clé s'affiche UNE seule fois — copiez-la tout de suite. Elle ressemble à « plm_live_ » suivi de trente-deux caractères.

  2. Poser la clé dans l'environnement du service

    Comme n'importe quel secret : dans les variables d'environnement, jamais dans le dépôt.

    PLUMAIL_API_KEY=plm_live_…

  3. Si vous venez de Resend : copiez le client minimal

    Un fichier, aucune dépendance, la même signature que le SDK que vous quittez. Le reste de votre code d'envoi ne bouge pas : il lit toujours { data, error } et data.id.

    curl -O https://plumail.fr/plumail-client.ts

// puis, dans votre code :
- const resend = new Resend(process.env.RESEND_API_KEY);
+ const plumail = new Plumail(process.env.PLUMAIL_API_KEY);

const { data, error } = await plumail.emails.send({ from, to, subject, html });
if (error) throw new Error(`Email delivery failed: ${error.message}`);

  4. Ou envoyer sans rien copier

    Aucune bibliothèque n'est nécessaire : un appel HTTP ordinaire suffit. La réponse est un 202 avec l'identifiant du message — l'e-mail est accepté, pas encore remis.

    const res = await fetch("https://plumail.fr/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PLUMAIL_API_KEY}`,
    "Content-Type": "application/json",
    // Une valeur unique par envoi : un réessai ne fera pas de doublon.
    "Idempotency-Key": factureId,
  },
  body: JSON.stringify({
    from: "Votre marque <[email protected]>",
    to: client.email,
    subject: "Votre facture",
    html: "<p>La voici.</p>",
  }),
});

if (!res.ok) {
  // Toujours la même forme : { error: { code, message, details } }.
  // Écrivez votre code contre « code », jamais contre « message ».
  const { error } = await res.json();
  throw new Error(`${error.code} — ${error.message}`);
}

const { id } = await res.json();

  5. Savoir si le message est arrivé

    Le statut évolue après l'envoi : sent, puis delivered, bounced ou complained. Une adresse qui rebondit entre automatiquement en liste de suppression — votre application n'a pas à s'en occuper.

    curl https://plumail.fr/api/v1/emails/ID \
  -H "Authorization: Bearer $PLUMAIL_API_KEY"

  6. Vérifier que c'est branché

    Demandez l'état du compte. C'est une lecture seule : rien n'est modifié, rien n'est envoyé. La réponse nomme votre espace et liste vos domaines d'envoi vérifiés — ce sont eux qui décident des adresses depuis lesquelles vous pourrez écrire.

    curl -s https://plumail.fr/api/v1/me \
  -H "Authorization: Bearer $PLUMAIL_API_KEY"

Si quelque chose coince

Les erreurs de l'API portent toutes un code lisible. Voici ceux qu'on rencontre au branchement.

422 suppressed_recipient sur un e-mail transactionnelLe destinataire s'est désinscrit de vos campagnes, ou son adresse est revenue en erreur. Plumail applique la liste de suppression AUSSI aux envois unitaires. Si vous voulez séparer le transactionnel de la newsletter, utilisez deux espaces.
401 invalid_api_keyLa clé est incomplète (un retour à la ligne s'est glissé au copier-coller) ou elle a été remplacée. Créez-en une neuve.
401 revoked_api_keyLa clé a été coupée dans Réglages → API. Créez-en une autre.
403 insufficient_scopeLa clé n'a pas le droit demandé. Les droits se choisissent à la création et ne se modifient plus : créez une clé avec le bon périmètre.
422 unverified_from_domainL'adresse d'expédition n'est pas sur un domaine vérifié de l'espace. Le message d'erreur liste ceux qui le sont. Pour en ajouter un : Domaines → Ajouter un domaine, puis poser les enregistrements DNS.
429 rate_limit_exceededPlus de 600 requêtes par minute pour cette clé. L'en-tête Retry-After dit combien de secondes attendre.

Aller plus loin