E-mail

Envoyer un e-mail

Envoyez un e-mail transactionnel ou marketing à un ou plusieurs destinataires. Prend en charge les corps HTML, les pièces jointes, le reply-to et les headers marketing.

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

Besoin d'envoyer à plusieurs destinataires à la fois ? Passez to sous forme de tableau — consultez Envoyer des e-mails en lot.

Paramètres du body

  • tostring | string[]obligatoire

    Adresse e-mail du destinataire ou tableau de 50 adresses maximum.

    ex. "user@example.com" or ["a@x.com", "b@x.com"]

  • fromstringobligatoire

    Adresse e-mail de l'expéditeur. Elle doit appartenir à un domaine vérifié de votre compte.

  • senderNamestringobligatoire

    Nom affiché dans la boîte de réception du destinataire.

  • subjectstringobligatoire

    Ligne d'objet de l'e-mail. Le HTML n'est pas pris en charge ici.

  • bodystringobligatoire

    Contenu HTML du corps de l'e-mail.

  • replyTostringfacultatif

    Adresse de réponse (reply-to). Par défaut, l'adresse de l'expéditeur si elle est omise.

  • transactionalbooleanfacultatif

    Mettez true pour le marquer comme transactionnel. Par défaut : false.

  • attachmentsobject[]facultatif

    Tableau d'objets pièce jointe. Consultez Envoyer des pièces jointes pour tous les détails.

  • retryRateLimitedintegerfacultatif

    Combien de cycles de 30 minutes continuer à essayer lorsque le fournisseur vous applique un rate limit (0–24, 25 par défaut). Consultez Options de livraison pour tous les détails.

  • retryUnavailableintegerfacultatif

    Combien de fois réessayer après une erreur temporaire (0–30). À utiliser avec retryUnavailableSeconds (10–3600). Consultez Options de livraison pour tous les détails.

  • ignoreHardBouncebooleanfacultatif

    Envoie même si l'adresse a fait un hard bounce au cours des 90 derniers jours. Par défaut : false. Consultez Options de livraison pour tous les détails.

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://mail.sendcorex.com/v3.0/send',
  {
    to: 'user@example.com',
    from: 'noreply@yourdomain.com',
    senderName: 'My App',
    subject: 'Welcome aboard!',
    body: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
    replyTo: 'support@yourdomain.com',
  },
  {
    headers: { Authorization: process.env.SENDCOREX_API_KEY },
  }
);

const { id, ids, recipients } = response.data;

Réponse

{
  "success": true,
  "message": "Email queued successfully",
  "code": "EMAIL_QUEUED_SUCCESS",
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
  "ids": [
    { "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f", "recipient": "user@example.com" }
  ],
  "recipients": 1,
  "scheduledAt": null
}

Requêtes idempotentes

Envoyez l'en-tête Idempotency-Key avec une valeur unique (nous recommandons un UUID v4) pour réessayer POST /v3.0/send sans risque. Si la connexion coupe ou en cas de timeout, réessayez avec la même clé et le même corps : nous renvoyons la réponse d'origine (même id d'e-mail) et l'e-mail n'est pas envoyé deux fois.

HTTP
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/json
  • Les clés sont valables 24 heures et propres à votre compte.

  • Caractères autorisés : lettres, chiffres, _ - : . (1 à 255 caractères).

  • Une réponse rejouée contient l'en-tête Idempotent-Replayed: true.

  • Utilisez une nouvelle clé pour chaque nouvel e-mail. Réutiliser une clé avec un autre corps renvoie 422 IDEMPOTENCY_KEY_REUSED.

  • Si la première requête est encore en cours, vous recevez 409 IDEMPOTENCY_IN_PROGRESS avec Retry-After: 1. Attendez et réessayez avec la même clé.

  • Les erreurs serveur (5xx) et les limites de débit (429) ne sont pas conservées : réessayer avec la même clé envoie normalement.

  • Sans l'en-tête, l'endpoint fonctionne comme avant.

↻

Réessai recommandé : en cas d'erreur réseau, de timeout, de 409, 429 ou 5xx, réessayez avec la même clé en backoff exponentiel (1 s, 2 s, 4 s…, jusqu'à 5 tentatives).

Exemple : clé UUID + réessai avec backoff

import { randomUUID } from 'node:crypto';

const RETRY_STATUS = new Set([409, 429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function sendEmail(email) {
  const key = randomUUID(); // one key per email, reused on every retry
  const body = JSON.stringify(email); // same body on every retry

  for (let attempt = 1; attempt <= 5; attempt++) {
    try {
      const res = await fetch('https://mail.sendcorex.com/v3.0/send', {
        method: 'POST',
        headers: {
          Authorization: process.env.SENDCOREX_API_KEY,
          'Idempotency-Key': key,
          'Content-Type': 'application/json',
        },
        body,
        signal: AbortSignal.timeout(15_000),
      });

      if (!RETRY_STATUS.has(res.status)) {
        const data = await res.json();
        if (!res.ok) throw new Error(data.code || 'SEND_FAILED');
        // Idempotent-Replayed: true → this is the original response (not sent twice)
        return { ...data, replayed: res.headers.get('Idempotent-Replayed') === 'true' };
      }
      if (attempt === 5) throw new Error('HTTP ' + res.status);
      const retryAfter = Number(res.headers.get('Retry-After')) * 1000;
      await sleep(retryAfter || 1000 * 2 ** (attempt - 1));
    } catch (err) {
      // network error or timeout: retry with the same key
      if (err.message?.startsWith('HTTP ') || attempt === 5 || (err.name !== 'TypeError' && err.name !== 'TimeoutError')) throw err;
      await sleep(1000 * 2 ** (attempt - 1));
    }
  }
}

const result = await sendEmail({
  to: 'user@example.com',
  from: 'noreply@yourdomain.com',
  senderName: 'My App',
  subject: 'Your receipt',
  body: '<p>Thanks for your order.</p>',
});
console.log(result.id, result.replayed);

Mes messages sont signalés comme spam

Chaque message passe par notre filtre anti-spam. Lorsqu'un message est signalé, la requête renvoie 403 avec le code SPAM_DETECTED et l'e-mail est placé en quarantaine.

403

Signalé comme spam

{
  "error": "Email content flagged as spam.",
  "code": "SPAM_DETECTED",
  "detectionId": "9c1e5a7d-2b4f-4e8a-a6d3-0f1b2c3d4e5f",
  "quarantine_id": "qtn_3f2a1b4c8e9d4f7a",
  "release_instructions": "POST /v3.0/quarantine/release with { quarantine_id }",
  "expires_in": "3 hours"
}
  • code

    Toujours SPAM_DETECTED pour cette réponse.

  • detectionId

    Identifiant de cette détection. Indiquez-le lorsque vous contactez le support.

  • quarantine_id

    Passez-le à /quarantine/release pour envoyer l'e-mail après vérification.

  • release_instructions

    Comment libérer l'e-mail.

  • expires_in

    Durée de conservation de l'enregistrement de quarantaine avant son expiration.

!

Un e-mail en quarantaine n'est pas livré. Utilisez /quarantine/release pour l'envoyer après vérification. L'enregistrement de quarantaine expire au bout de 3 heures.

Si quarantine_id, release_instructions et expires_in valent null, l'e-mail a été bloqué sans enregistrement de quarantaine. Il ne peut pas être libéré : corrigez le contenu et renvoyez-le.

Les erreurs renvoient un objet JSON avec error, code et responseTime.

  • 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.