Se connecterCréer un compte gratuit

Langue

Se connecterCréer un compte gratuit
Guide d'installation

Brancher Mailcheer 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 Mailcheer : 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 à « mch_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.

    MAILCHEER_API_KEY=mch_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://mailcheer.com/mailcheer-client.fr.ts

// puis, dans votre code :
- const resend = new Resend(process.env.RESEND_API_KEY);
+ const mailcheer = new Mailcheer(process.env.MAILCHEER_API_KEY);

const { data, error } = await mailcheer.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://mailcheer.com/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILCHEER_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 <bonjour@votredomaine.fr>",
    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://mailcheer.com/api/v1/emails/ID \
  -H "Authorization: Bearer $MAILCHEER_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://mailcheer.com/api/v1/me \
  -H "Authorization: Bearer $MAILCHEER_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 transactionnelL'adresse du destinataire est revenue en erreur, il s'est plaint, ou vous l'avez retirée à la main : ces trois motifs refusent aussi les envois unitaires. Une simple désinscription ne refuse que les envois qui portent unsubscribe_url.
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