E-mail

Headers de désinscription

Ajoutez des headers List-Unsubscribe à vos e-mails pour que les destinataires (et les fournisseurs comme Gmail et Yahoo) puissent se désinscrire sans signaler votre e-mail comme spam. Cela améliore nettement la délivrabilité des envois en masse et marketing.

POSThttps://mail.sendcorex.com/v3.0/send
!

Les fournisseurs de messagerie recommandent vivement (et parfois exigent) List-Unsubscribe sur tout envoi en masse. L'absence de ce header sur des envois à fort volume peut nuire à l'arrivée en boîte de réception.

i

Les headers se placent dans l'objet headers de la requête d'envoi. Pour les règles de nommage applicables à tous les autres headers, consultezHeaders personnalisés.

Headers pris en charge

  • List-Unsubscribefacultatif

    Liste de méthodes de désinscription séparées par des virgules, entre chevrons. Accepte un lien mailto: et un lien https:.

    ex. "<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>"

  • List-Unsubscribe-Postfacultatif

    Active la désinscription en un clic de Gmail/Yahoo. Obligatoire si vous voulez que le bouton « Se désabonner » apparaisse directement dans l'interface de la boîte de réception. Doit valoir exactement :

    ex. "List-Unsubscribe=One-Click"

  • List-Idfacultatif

    Identifie la liste de diffusion à laquelle appartient cet e-mail.

    ex. "My List <mylist.yourdomain.com>"

Lien de désinscription automatique

Si vous n'avez pas votre propre système de désinscription, Sendcorex peut générer et gérer le lien de désinscription et le mailto pour vous. Définissez unsubscribe: true dans la requête d'envoi et incluez l'un des placeholders pris en charge dans le corps, à l'endroit où vous voulez insérer le lien.

Placeholders pris en charge

  • [unsubscribe_url]
  • [unsubscribe]
  • [unsub_url]
  • [opt_out_url]

Utilisez l'un d'eux dans un href (ou n'importe où dans le corps). Sendcorex le remplace par le vrai lien de désinscription de chaque destinataire avant l'envoi.

unsubscribe: true, sans système propre

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "senderName": "My App",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "replyTo": "support@yourdomain.com",
  "unsubscribe": true
}
!

Si unsubscribe: true est défini mais qu'aucun des placeholders pris en charge n'est trouvé dans le corps, la requête échoue avec MISSING_UNSUBSCRIBE_PLACEHOLDER. Consultez laréponse 400.

Liste de contacts

facultatif

contact_list n'est pas obligatoire. Il détermine seulement dans quelle liste le destinataire est enregistré, pour le suivi et l'organisation. Il n'a rien à voir avec le lien de désinscription lui-même.

Sans contact_list (par défaut)

Le contact est automatiquement enregistré dans une liste par défaut nommée "API Contacts". Ce nom ne peut pas être modifié. Vous pouvez la consulter à tout moment dans voslistes de contacts.

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "unsubscribe": true
}

Avec contact_list (nom personnalisé)

Si la liste n'existe pas encore, elle est créée automatiquement. C'est utile pour séparer les audiences, par exemple une liste par campagne ou par plateforme.

  • "CRM 2026 - Gmail"
  • "Newsletter - Trial Users"
  • "Support Tickets"
{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "unsubscribe": true,
  "contact_list": "CRM 2026 - Gmail"
}

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://mail.sendcorex.com/v3.0/send',
  {
    to: 'contact@gmail.com',
    from: 'noreply@yourdomain.com',
    senderName: 'My App',
    subject: 'Welcome aboard!',
    body: '<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href="[unsubscribe]">Unsubscribe</a></p>',
    unsubscribe: true,
    contact_list: 'CRM 2026 - Gmail',
    headers: {
      'List-Id': 'My List <mylist.yourdomain.com>',
      'List-Unsubscribe':
        '<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>',
      'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
    },
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } }
);

const { id } = response.data;

Réponse

{
  "success": true,
  "message": "Email queued successfully",
  "code": "EMAIL_QUEUED_SUCCESS",
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
}

Les erreurs renvoient un objet JSON avec error et code.

  • 401MISSING_AUTH_HEADER

    Aucun en-tête Authorization n'est présent.

  • 401INVALID_API_KEY

    La clé API est invalide ou révoquée.

  • 401ACCOUNT_BLOCKED

    Le compte a été bloqué.

  • 401NO_CREDITS_LEFT

    Crédits e-mail insuffisants pour tous les destinataires. Chaque adresse dans to, cc et bcc utilise 1 crédit.

  • 401DOMAIN_NOT_VALIDATED

    Domaine de l'expéditeur non vérifié.

  • 401LISTED_SPAM_HAUS

    Le domaine de l'expéditeur est listé sur Spamhaus.

  • 401ISP_DOMAIN_BLOCKED

    L'envoi depuis des domaines connus (gmail.com, outlook.com, etc.) n'est pas autorisé.

  • 401FROM_HEADER_DOMAIN_MISMATCH

    Domaine de l'en-tête From non autorisé pour cet expéditeur.

  • 401USER_NOT_FOUND

    Utilisateur introuvable.

  • 401MISSING_USER_PRIVILEGES

    Privilèges utilisateur manquants.

  • 401EMAIL_CREDITS_NOT_FOUND

    Erreur lors de la récupération des crédits e-mail.

  • 401EMAIL_NOT_VALIDATED

    L'adresse e-mail du compte n'a pas encore été vérifiée.

  • 429CREDENTIAL_TEMPORARILY_BLOCKED

    Clé API temporairement bloquée après des violations répétées de la politique.

  • 429IP_TEMPORARILY_BLOCKED

    IP de la requête temporairement bloquée après des violations répétées de la politique.

  • 429TOO_MANY_CONCURRENT_CONNECTIONS

    Trop de requêtes simultanées depuis cette IP. Réessayez dans un instant.

  • 400INVALID_JSON

    Le corps de la requête n'est pas un JSON valide.

  • 400MISSING_FROM

    Le champ from est manquant ou vide.

  • 400INVALID_FROM_FORMAT

    Le champ from doit être une adresse e-mail valide.

  • 400MISSING_SENDERNAME

    Le champ senderName est manquant ou vide.

  • 400INVALID_SENDERNAME_FORMAT

    Le champ senderName contient des caractères invalides.

  • 400MISSING_SUBJECT

    Le champ subject est manquant ou vide.

  • 400MISSING_BODY

    Le champ body est manquant ou vide.

  • 400MISSING_TOADDRESS

    Le champ to est manquant ou vide.

  • 400MISSING_TO

    Le champ to est manquant ou vide.

  • 400INVALID_TOADDRESS

    Une ou plusieurs adresses de destinataire sont mal formées.

  • 400TOADDRESS_LIMIT_EXCEEDED

    Plus de 50 destinataires dans le tableau to.

  • 400INVALID_CCADDRESS

    Une ou plusieurs adresses cc sont mal formées.

  • 400INVALID_BCCADDRESS

    Une ou plusieurs adresses bcc sont mal formées.

  • 400RECIPIENT_LIMIT_EXCEEDED

    to, cc et bcc réunis comptent plus de 50 destinataires uniques.

  • 400INVALID_SCHEDULED_AT

    scheduled_at n'est pas une date valide ou est dans le passé.

  • 400INVALID_SENDER_FORMAT

    Le format de l'e-mail de l'expéditeur est invalide.

  • 400HEADER_NOT_ALLOWED

    La clé de l'en-tête personnalisé n'est pas dans la liste autorisée (List-Unsubscribe, List-Id, X-*, etc.).

  • 400INVALID_HEADER_VALUE

    La valeur de l'en-tête contient des caractères invalides (CR/LF interdits).

  • 400DANGEROUS_ATTACHMENT

    Une ou plusieurs pièces jointes ont été bloquées pour des raisons de sécurité.

  • 400INVALID_ATTACHMENT

    Le contenu d'une pièce jointe n'est pas un base64 valide.

  • 400MISSING_UNSUBSCRIBE_PLACEHOLDER

    unsubscribe vaut true mais le body ne contient aucun placeholder de désinscription ([unsubscribe_url], [unsubscribe], [unsub_url] ou [opt_out_url]).

  • 403ACCOUNT_RESTRICTED

    Le compte est temporairement restreint.

  • 403DAILY_LIMIT

    Limite quotidienne d'envoi d'e-mails atteinte.

  • 403MARKETING_LIMIT_REACHED

    Limite quotidienne marketing du plan gratuit atteinte : 30 e-mails marketing ou de prospection à froid par jour, comptés par destinataire sur une fenêtre glissante de 24 heures. La réponse contient limit, used, recipients et upgradeUrl. Les e-mails transactionnels partent toujours ; rien n'est mis en file d'attente.

  • 403FORBIDDEN_HTML_CONTENT

    Le HTML contient du contenu actif interdit dans les e-mails (script, iframe, form, input, button, embed, object, svg, handlers on*, liens javascript:, meta refresh…). La réponse liste les éléments détectés. Utilisez un <a> stylé au lieu de boutons ou de formulaires.

  • 403SPAM_DETECTED

    Contenu de l'e-mail signalé comme spam. La réponse inclut le quarantine_id et les instructions de libération.

  • 403SENDER_NAME_MISMATCH

    Plusieurs noms d'expéditeur détectés pour la même adresse.

  • 403FOLLOWUP_PATTERN_DETECTED

    Contenu de l'e-mail signalé comme schéma répété de relance suspecte.

  • 403SCAM_PATTERN_DETECTED

    Contenu de l'e-mail signalé comme schéma d'arnaque.

  • 403ACCOUNT_SUSPENDED_SPOOFING

    Compte suspendu après des tentatives répétées d'usurpation de l'en-tête From.

  • 409IDEMPOTENCY_IN_PROGRESS

    Une requête avec la même Idempotency-Key est encore en cours de traitement. Attendez (Retry-After: 1) et réessayez avec la même clé.

  • 422IDEMPOTENCY_KEY_REUSED

    Cette Idempotency-Key a déjà été utilisée avec un autre corps. Utilisez une nouvelle clé pour chaque nouvel e-mail.

  • 500INTERNAL_SERVER_ERROR

    Erreur serveur inattendue. Réessayez.

  • 500PARSE_ERROR

    Échec du traitement du contenu de l'e-mail (échec du parsing MIME).

  • 500PERSIST_FAILED

    Échec de la mise en file de l'e-mail (échec d'écriture en base de données).

  • 503AUTH_UNAVAILABLE

    Impossible de valider la clé API pour le moment. Réessayez.

  • 503UNSUBSCRIBE_UNAVAILABLE

    Service de lien de désinscription temporairement indisponible. Réessayez plus tard.