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.
https://mail.sendcorex.com/v3.0/sendBesoin 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[]obligatoireAdresse e-mail du destinataire ou tableau de 50 adresses maximum.
ex.
"user@example.com" or ["a@x.com", "b@x.com"]fromstringobligatoireAdresse e-mail de l'expéditeur. Elle doit appartenir à un domaine vérifié de votre compte.
senderNamestringobligatoireNom affiché dans la boîte de réception du destinataire.
subjectstringobligatoireLigne d'objet de l'e-mail. Le HTML n'est pas pris en charge ici.
bodystringobligatoireContenu HTML du corps de l'e-mail.
replyTostringfacultatifAdresse de réponse (reply-to). Par défaut, l'adresse de l'expéditeur si elle est omise.
transactionalbooleanfacultatifMettez true pour le marquer comme transactionnel. Par défaut : false.
attachmentsobject[]facultatifTableau d'objets pièce jointe. Consultez Envoyer des pièces jointes pour tous les détails.
retryRateLimitedintegerfacultatifCombien 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.
retryUnavailableintegerfacultatifCombien 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.
ignoreHardBouncebooleanfacultatifEnvoie 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.
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/jsonLes 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_PROGRESSavecRetry-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.
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"
}codeToujours SPAM_DETECTED pour cette réponse.
detectionIdIdentifiant de cette détection. Indiquez-le lorsque vous contactez le support.
quarantine_idPassez-le à /quarantine/release pour envoyer l'e-mail après vérification.
release_instructionsComment libérer l'e-mail.
expires_inDuré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.
Erreurs
Tous les codes d'erreur →Les erreurs renvoient un objet JSON avec error, code et responseTime.
- 401
MISSING_AUTH_HEADERAucun en-tête Authorization n'est présent.
- 401
INVALID_API_KEYLa clé API est invalide ou révoquée.
- 401
ACCOUNT_BLOCKEDLe compte a été bloqué.
- 401
NO_CREDITS_LEFTCrédits e-mail insuffisants pour tous les destinataires. Chaque adresse dans to, cc et bcc utilise 1 crédit.
- 401
DOMAIN_NOT_VALIDATEDDomaine de l'expéditeur non vérifié.
- 401
LISTED_SPAM_HAUSLe domaine de l'expéditeur est listé sur Spamhaus.
- 401
ISP_DOMAIN_BLOCKEDL'envoi depuis des domaines connus (gmail.com, outlook.com, etc.) n'est pas autorisé.
- 401
FROM_HEADER_DOMAIN_MISMATCHDomaine de l'en-tête From non autorisé pour cet expéditeur.
- 401
USER_NOT_FOUNDUtilisateur introuvable.
- 401
MISSING_USER_PRIVILEGESPrivilèges utilisateur manquants.
- 401
EMAIL_CREDITS_NOT_FOUNDErreur lors de la récupération des crédits e-mail.
- 401
EMAIL_NOT_VALIDATEDL'adresse e-mail du compte n'a pas encore été vérifiée.
- 429
CREDENTIAL_TEMPORARILY_BLOCKEDClé API temporairement bloquée après des violations répétées de la politique.
- 429
IP_TEMPORARILY_BLOCKEDIP de la requête temporairement bloquée après des violations répétées de la politique.
- 429
TOO_MANY_CONCURRENT_CONNECTIONSTrop de requêtes simultanées depuis cette IP. Réessayez dans un instant.
- 400
INVALID_JSONLe corps de la requête n'est pas un JSON valide.
- 400
MISSING_FROMLe champ from est manquant ou vide.
- 400
INVALID_FROM_FORMATLe champ from doit être une adresse e-mail valide.
- 400
MISSING_SENDERNAMELe champ senderName est manquant ou vide.
- 400
INVALID_SENDERNAME_FORMATLe champ senderName contient des caractères invalides.
- 400
MISSING_SUBJECTLe champ subject est manquant ou vide.
- 400
MISSING_BODYLe champ body est manquant ou vide.
- 400
MISSING_TOADDRESSLe champ to est manquant ou vide.
- 400
MISSING_TOLe champ to est manquant ou vide.
- 400
INVALID_TOADDRESSUne ou plusieurs adresses de destinataire sont mal formées.
- 400
TOADDRESS_LIMIT_EXCEEDEDPlus de 50 destinataires dans le tableau to.
- 400
INVALID_CCADDRESSUne ou plusieurs adresses cc sont mal formées.
- 400
INVALID_BCCADDRESSUne ou plusieurs adresses bcc sont mal formées.
- 400
RECIPIENT_LIMIT_EXCEEDEDto, cc et bcc réunis comptent plus de 50 destinataires uniques.
- 400
INVALID_SCHEDULED_ATscheduled_at n'est pas une date valide ou est dans le passé.
- 400
INVALID_SENDER_FORMATLe format de l'e-mail de l'expéditeur est invalide.
- 400
HEADER_NOT_ALLOWEDLa clé de l'en-tête personnalisé n'est pas dans la liste autorisée (List-Unsubscribe, List-Id, X-*, etc.).
- 400
INVALID_HEADER_VALUELa valeur de l'en-tête contient des caractères invalides (CR/LF interdits).
- 400
DANGEROUS_ATTACHMENTUne ou plusieurs pièces jointes ont été bloquées pour des raisons de sécurité.
- 400
INVALID_ATTACHMENTLe contenu d'une pièce jointe n'est pas un base64 valide.
- 400
MISSING_UNSUBSCRIBE_PLACEHOLDERunsubscribe vaut true mais le body ne contient aucun placeholder de désinscription ([unsubscribe_url], [unsubscribe], [unsub_url] ou [opt_out_url]).
- 403
ACCOUNT_RESTRICTEDLe compte est temporairement restreint.
- 403
DAILY_LIMITLimite quotidienne d'envoi d'e-mails atteinte.
- 403
MARKETING_LIMIT_REACHEDLimite 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.
- 403
FORBIDDEN_HTML_CONTENTLe 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.
- 403
SPAM_DETECTEDContenu de l'e-mail signalé comme spam. La réponse inclut le quarantine_id et les instructions de libération.
- 403
SENDER_NAME_MISMATCHPlusieurs noms d'expéditeur détectés pour la même adresse.
- 403
FOLLOWUP_PATTERN_DETECTEDContenu de l'e-mail signalé comme schéma répété de relance suspecte.
- 403
SCAM_PATTERN_DETECTEDContenu de l'e-mail signalé comme schéma d'arnaque.
- 403
ACCOUNT_SUSPENDED_SPOOFINGCompte suspendu après des tentatives répétées d'usurpation de l'en-tête From.
- 409
IDEMPOTENCY_IN_PROGRESSUne 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é.
- 422
IDEMPOTENCY_KEY_REUSEDCette Idempotency-Key a déjà été utilisée avec un autre corps. Utilisez une nouvelle clé pour chaque nouvel e-mail.
- 500
INTERNAL_SERVER_ERRORErreur serveur inattendue. Réessayez.
- 500
PARSE_ERRORÉchec du traitement du contenu de l'e-mail (échec du parsing MIME).
- 500
PERSIST_FAILEDÉchec de la mise en file de l'e-mail (échec d'écriture en base de données).
- 503
AUTH_UNAVAILABLEImpossible de valider la clé API pour le moment. Réessayez.
- 503
UNSUBSCRIBE_UNAVAILABLEService de lien de désinscription temporairement indisponible. Réessayez plus tard.