Kirim Email
Kirim email transaksional atau marketing ke satu atau beberapa penerima. Mendukung body HTML, lampiran, reply-to, dan header marketing.
https://mail.sendcorex.com/v3.0/sendPerlu mengirim ke beberapa penerima sekaligus? Kirim to sebagai array — lihat Kirim Email Massal.
Parameter body
tostring | string[]wajibAlamat email penerima atau array berisi hingga 50 alamat.
mis.
"user@example.com" or ["a@x.com", "b@x.com"]fromstringwajibAlamat email pengirim. Harus milik domain terverifikasi di akun Anda.
senderNamestringwajibNama tampilan di kotak masuk penerima.
subjectstringwajibBaris subjek email. HTML tidak didukung di sini.
bodystringwajibKonten HTML untuk body email.
replyTostringopsionalAlamat balasan (reply-to). Jika tidak diisi, menggunakan alamat pengirim.
transactionalbooleanopsionalAtur ke true untuk menandai sebagai transaksional. Default-nya false.
attachmentsobject[]opsionalArray objek lampiran. Lihat Kirim Lampiran untuk detail lengkap.
retryRateLimitedintegeropsionalBerapa siklus 30 menit untuk terus mencoba saat provider menerapkan rate limit (0–24, default 25). Lihat Opsi pengiriman untuk detail lengkap.
retryUnavailableintegeropsionalBerapa kali mencoba lagi setelah error sementara (0–30). Gunakan bersama retryUnavailableSeconds (10–3600). Lihat Opsi pengiriman untuk detail lengkap.
ignoreHardBouncebooleanopsionalTetap kirim meskipun alamat mengalami hard bounce dalam 90 hari terakhir. Default-nya false. Lihat Opsi pengiriman untuk detail lengkap.
Mulai cepat
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;Respons
{
"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
}Permintaan idempoten
Kirim header Idempotency-Key dengan nilai unik apa pun (kami sarankan UUID v4) agar aman mengulang POST /v3.0/send. Jika koneksi terputus atau timeout, ulangi dengan kunci dan body yang sama: kami mengembalikan respons asli (id email yang sama) dan email tidak terkirim dua kali.
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/jsonKunci berlaku 24 jam dan khusus untuk akun Anda.
Karakter yang diizinkan: huruf, angka,
_ - : .(1–255 karakter).Respons yang diputar ulang memiliki header
Idempotent-Replayed: true.Gunakan kunci baru untuk setiap email baru. Memakai ulang kunci dengan body berbeda mengembalikan
422 IDEMPOTENCY_KEY_REUSED.Jika permintaan pertama masih diproses, Anda menerima
409 IDEMPOTENCY_IN_PROGRESSdenganRetry-After: 1. Tunggu lalu ulangi dengan kunci yang sama.Error server (
5xx) dan batas laju (429) tidak disimpan: mengulang dengan kunci yang sama akan mengirim seperti biasa.Tanpa header ini, endpoint bekerja seperti sebelumnya.
Retry yang disarankan: saat error jaringan, timeout, 409, 429 atau 5xx, ulangi dengan kunci yang sama memakai backoff eksponensial (1 s, 2 s, 4 s…, hingga 5 percobaan).
Contoh: kunci UUID + retry dengan 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);Pesan saya ditandai sebagai spam
Setiap pesan melewati filter anti-spam kami. Jika sebuah pesan ditandai, permintaan mengembalikan 403 dengan kode SPAM_DETECTED dan email ditahan di karantina.
Ditandai sebagai 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"
}codeSelalu SPAM_DETECTED untuk respons ini.
detectionIdPengenal deteksi ini. Sertakan saat menghubungi support.
quarantine_idKirim ini ke /quarantine/release untuk mengirim email setelah ditinjau.
release_instructionsCara merilis email.
expires_inBerapa lama catatan karantina disimpan sebelum kedaluwarsa.
Email yang dikarantina tidak dikirim. Gunakan /quarantine/release untuk mengirimnya setelah ditinjau. Catatan karantina kedaluwarsa setelah 3 jam.
Jika quarantine_id, release_instructions, dan expires_in bernilai null, email diblokir tanpa catatan karantina. Email tidak bisa dirilis: perbaiki kontennya dan kirim lagi.
Error
Semua kode error →Error mengembalikan objek JSON dengan error, code, dan responseTime.
- 401
MISSING_AUTH_HEADERTidak ada header Authorization.
- 401
INVALID_API_KEYAPI key tidak valid atau sudah dicabut.
- 401
ACCOUNT_BLOCKEDAkun telah diblokir.
- 401
NO_CREDITS_LEFTKredit email tidak cukup untuk semua penerima. Setiap alamat di to, cc, dan bcc memakai 1 kredit.
- 401
DOMAIN_NOT_VALIDATEDDomain pengirim belum diverifikasi.
- 401
LISTED_SPAM_HAUSDomain pengirim terdaftar di Spamhaus.
- 401
ISP_DOMAIN_BLOCKEDMengirim dari domain umum (gmail.com, outlook.com, dll.) tidak diizinkan.
- 401
FROM_HEADER_DOMAIN_MISMATCHDomain header From tidak diizinkan untuk pengirim ini.
- 401
USER_NOT_FOUNDPengguna tidak ditemukan.
- 401
MISSING_USER_PRIVILEGESHak akses pengguna tidak cukup.
- 401
EMAIL_CREDITS_NOT_FOUNDGagal mengambil kredit email.
- 401
EMAIL_NOT_VALIDATEDAlamat email akun belum diverifikasi.
- 429
CREDENTIAL_TEMPORARILY_BLOCKEDAPI key diblokir sementara karena pelanggaran kebijakan berulang.
- 429
IP_TEMPORARILY_BLOCKEDIP peminta diblokir sementara karena pelanggaran kebijakan berulang.
- 429
TOO_MANY_CONCURRENT_CONNECTIONSTerlalu banyak request bersamaan dari IP ini. Coba lagi sebentar lagi.
- 400
INVALID_JSONBody request bukan JSON yang valid.
- 400
MISSING_FROMField from tidak ada atau kosong.
- 400
INVALID_FROM_FORMATField from harus berupa alamat email yang valid.
- 400
MISSING_SENDERNAMEField senderName tidak ada atau kosong.
- 400
INVALID_SENDERNAME_FORMATField senderName berisi karakter yang tidak valid.
- 400
MISSING_SUBJECTField subject tidak ada atau kosong.
- 400
MISSING_BODYField body tidak ada atau kosong.
- 400
MISSING_TOADDRESSField to tidak ada atau kosong.
- 400
MISSING_TOField to tidak ada atau kosong.
- 400
INVALID_TOADDRESSSatu atau lebih alamat penerima tidak valid.
- 400
TOADDRESS_LIMIT_EXCEEDEDLebih dari 50 penerima di array to.
- 400
INVALID_CCADDRESSSatu atau lebih alamat cc tidak valid.
- 400
INVALID_BCCADDRESSSatu atau lebih alamat bcc tidak valid.
- 400
RECIPIENT_LIMIT_EXCEEDEDto, cc, dan bcc jika digabung memiliki lebih dari 50 penerima unik.
- 400
INVALID_SCHEDULED_ATscheduled_at bukan tanggal yang valid atau sudah lewat.
- 400
INVALID_SENDER_FORMATFormat email pengirim tidak valid.
- 400
HEADER_NOT_ALLOWEDKunci header kustom tidak ada di daftar yang diizinkan (List-Unsubscribe, List-Id, X-*, dll.).
- 400
INVALID_HEADER_VALUENilai header berisi karakter tidak valid (CR/LF tidak diizinkan).
- 400
DANGEROUS_ATTACHMENTSatu atau lebih lampiran diblokir demi keamanan.
- 400
INVALID_ATTACHMENTKonten lampiran bukan base64 yang valid.
- 400
MISSING_UNSUBSCRIBE_PLACEHOLDERunsubscribe bernilai true tetapi body tidak memiliki placeholder berhenti berlangganan ([unsubscribe_url], [unsubscribe], [unsub_url], atau [opt_out_url]).
- 403
ACCOUNT_RESTRICTEDAkun dibatasi sementara.
- 403
DAILY_LIMITBatas harian pengiriman email tercapai.
- 403
MARKETING_LIMIT_REACHEDBatas harian email marketing paket gratis tercapai: 30 email marketing atau cold outreach per hari, dihitung per penerima dalam jendela bergulir 24 jam. Respons berisi limit, used, recipients, dan upgradeUrl. Email transaksional tetap terkirim; tidak ada yang diantrekan.
- 403
FORBIDDEN_HTML_CONTENTHTML berisi konten aktif yang tidak diizinkan di email (script, iframe, form, input, button, embed, object, svg, handler on*, link javascript:, meta refresh…). Respons mencantumkan temuannya. Gunakan <a> yang diberi gaya sebagai pengganti tombol atau formulir.
- 403
SPAM_DETECTEDKonten email ditandai sebagai spam. Respons menyertakan quarantine_id dan petunjuk rilis.
- 403
SENDER_NAME_MISMATCHTerdeteksi beberapa nama pengirim untuk alamat yang sama.
- 403
FOLLOWUP_PATTERN_DETECTEDKonten email ditandai sebagai pola tindak lanjut mencurigakan yang berulang.
- 403
SCAM_PATTERN_DETECTEDKonten email ditandai sebagai pola penipuan.
- 403
ACCOUNT_SUSPENDED_SPOOFINGAkun ditangguhkan karena berulang kali mencoba memalsukan header From.
- 409
IDEMPOTENCY_IN_PROGRESSPermintaan dengan Idempotency-Key yang sama masih diproses. Tunggu (Retry-After: 1) lalu ulangi dengan kunci yang sama.
- 422
IDEMPOTENCY_KEY_REUSEDIdempotency-Key ini sudah dipakai dengan body yang berbeda. Gunakan kunci baru untuk setiap email baru.
- 500
INTERNAL_SERVER_ERRORError server tak terduga. Coba lagi.
- 500
PARSE_ERRORGagal memproses konten email (gagal parse MIME).
- 500
PERSIST_FAILEDGagal memasukkan email ke antrean (gagal menyimpan ke database).
- 503
AUTH_UNAVAILABLEAPI key tidak dapat divalidasi saat ini. Coba lagi.
- 503
UNSUBSCRIBE_UNAVAILABLELayanan tautan berhenti berlangganan sementara tidak tersedia. Coba lagi nanti.