Email

Kirim Email

Kirim email transaksional atau marketing ke satu atau beberapa penerima. Mendukung body HTML, lampiran, reply-to, dan header marketing.

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

Perlu mengirim ke beberapa penerima sekaligus? Kirim to sebagai array — lihat Kirim Email Massal.

Parameter body

  • tostring | string[]wajib

    Alamat email penerima atau array berisi hingga 50 alamat.

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

  • fromstringwajib

    Alamat email pengirim. Harus milik domain terverifikasi di akun Anda.

  • senderNamestringwajib

    Nama tampilan di kotak masuk penerima.

  • subjectstringwajib

    Baris subjek email. HTML tidak didukung di sini.

  • bodystringwajib

    Konten HTML untuk body email.

  • replyTostringopsional

    Alamat balasan (reply-to). Jika tidak diisi, menggunakan alamat pengirim.

  • transactionalbooleanopsional

    Atur ke true untuk menandai sebagai transaksional. Default-nya false.

  • attachmentsobject[]opsional

    Array objek lampiran. Lihat Kirim Lampiran untuk detail lengkap.

  • retryRateLimitedintegeropsional

    Berapa siklus 30 menit untuk terus mencoba saat provider menerapkan rate limit (0–24, default 25). Lihat Opsi pengiriman untuk detail lengkap.

  • retryUnavailableintegeropsional

    Berapa kali mencoba lagi setelah error sementara (0–30). Gunakan bersama retryUnavailableSeconds (10–3600). Lihat Opsi pengiriman untuk detail lengkap.

  • ignoreHardBouncebooleanopsional

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

HTTP
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/json
  • Kunci 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_PROGRESS dengan Retry-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.

403

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"
}
  • code

    Selalu SPAM_DETECTED untuk respons ini.

  • detectionId

    Pengenal deteksi ini. Sertakan saat menghubungi support.

  • quarantine_id

    Kirim ini ke /quarantine/release untuk mengirim email setelah ditinjau.

  • release_instructions

    Cara merilis email.

  • expires_in

    Berapa 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 mengembalikan objek JSON dengan error, code, dan responseTime.

  • 401MISSING_AUTH_HEADER

    Tidak ada header Authorization.

  • 401INVALID_API_KEY

    API key tidak valid atau sudah dicabut.

  • 401ACCOUNT_BLOCKED

    Akun telah diblokir.

  • 401NO_CREDITS_LEFT

    Kredit email tidak cukup untuk semua penerima. Setiap alamat di to, cc, dan bcc memakai 1 kredit.

  • 401DOMAIN_NOT_VALIDATED

    Domain pengirim belum diverifikasi.

  • 401LISTED_SPAM_HAUS

    Domain pengirim terdaftar di Spamhaus.

  • 401ISP_DOMAIN_BLOCKED

    Mengirim dari domain umum (gmail.com, outlook.com, dll.) tidak diizinkan.

  • 401FROM_HEADER_DOMAIN_MISMATCH

    Domain header From tidak diizinkan untuk pengirim ini.

  • 401USER_NOT_FOUND

    Pengguna tidak ditemukan.

  • 401MISSING_USER_PRIVILEGES

    Hak akses pengguna tidak cukup.

  • 401EMAIL_CREDITS_NOT_FOUND

    Gagal mengambil kredit email.

  • 401EMAIL_NOT_VALIDATED

    Alamat email akun belum diverifikasi.

  • 429CREDENTIAL_TEMPORARILY_BLOCKED

    API key diblokir sementara karena pelanggaran kebijakan berulang.

  • 429IP_TEMPORARILY_BLOCKED

    IP peminta diblokir sementara karena pelanggaran kebijakan berulang.

  • 429TOO_MANY_CONCURRENT_CONNECTIONS

    Terlalu banyak request bersamaan dari IP ini. Coba lagi sebentar lagi.

  • 400INVALID_JSON

    Body request bukan JSON yang valid.

  • 400MISSING_FROM

    Field from tidak ada atau kosong.

  • 400INVALID_FROM_FORMAT

    Field from harus berupa alamat email yang valid.

  • 400MISSING_SENDERNAME

    Field senderName tidak ada atau kosong.

  • 400INVALID_SENDERNAME_FORMAT

    Field senderName berisi karakter yang tidak valid.

  • 400MISSING_SUBJECT

    Field subject tidak ada atau kosong.

  • 400MISSING_BODY

    Field body tidak ada atau kosong.

  • 400MISSING_TOADDRESS

    Field to tidak ada atau kosong.

  • 400MISSING_TO

    Field to tidak ada atau kosong.

  • 400INVALID_TOADDRESS

    Satu atau lebih alamat penerima tidak valid.

  • 400TOADDRESS_LIMIT_EXCEEDED

    Lebih dari 50 penerima di array to.

  • 400INVALID_CCADDRESS

    Satu atau lebih alamat cc tidak valid.

  • 400INVALID_BCCADDRESS

    Satu atau lebih alamat bcc tidak valid.

  • 400RECIPIENT_LIMIT_EXCEEDED

    to, cc, dan bcc jika digabung memiliki lebih dari 50 penerima unik.

  • 400INVALID_SCHEDULED_AT

    scheduled_at bukan tanggal yang valid atau sudah lewat.

  • 400INVALID_SENDER_FORMAT

    Format email pengirim tidak valid.

  • 400HEADER_NOT_ALLOWED

    Kunci header kustom tidak ada di daftar yang diizinkan (List-Unsubscribe, List-Id, X-*, dll.).

  • 400INVALID_HEADER_VALUE

    Nilai header berisi karakter tidak valid (CR/LF tidak diizinkan).

  • 400DANGEROUS_ATTACHMENT

    Satu atau lebih lampiran diblokir demi keamanan.

  • 400INVALID_ATTACHMENT

    Konten lampiran bukan base64 yang valid.

  • 400MISSING_UNSUBSCRIBE_PLACEHOLDER

    unsubscribe bernilai true tetapi body tidak memiliki placeholder berhenti berlangganan ([unsubscribe_url], [unsubscribe], [unsub_url], atau [opt_out_url]).

  • 403ACCOUNT_RESTRICTED

    Akun dibatasi sementara.

  • 403DAILY_LIMIT

    Batas harian pengiriman email tercapai.

  • 403MARKETING_LIMIT_REACHED

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

  • 403FORBIDDEN_HTML_CONTENT

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

  • 403SPAM_DETECTED

    Konten email ditandai sebagai spam. Respons menyertakan quarantine_id dan petunjuk rilis.

  • 403SENDER_NAME_MISMATCH

    Terdeteksi beberapa nama pengirim untuk alamat yang sama.

  • 403FOLLOWUP_PATTERN_DETECTED

    Konten email ditandai sebagai pola tindak lanjut mencurigakan yang berulang.

  • 403SCAM_PATTERN_DETECTED

    Konten email ditandai sebagai pola penipuan.

  • 403ACCOUNT_SUSPENDED_SPOOFING

    Akun ditangguhkan karena berulang kali mencoba memalsukan header From.

  • 409IDEMPOTENCY_IN_PROGRESS

    Permintaan dengan Idempotency-Key yang sama masih diproses. Tunggu (Retry-After: 1) lalu ulangi dengan kunci yang sama.

  • 422IDEMPOTENCY_KEY_REUSED

    Idempotency-Key ini sudah dipakai dengan body yang berbeda. Gunakan kunci baru untuk setiap email baru.

  • 500INTERNAL_SERVER_ERROR

    Error server tak terduga. Coba lagi.

  • 500PARSE_ERROR

    Gagal memproses konten email (gagal parse MIME).

  • 500PERSIST_FAILED

    Gagal memasukkan email ke antrean (gagal menyimpan ke database).

  • 503AUTH_UNAVAILABLE

    API key tidak dapat divalidasi saat ini. Coba lagi.

  • 503UNSUBSCRIBE_UNAVAILABLE

    Layanan tautan berhenti berlangganan sementara tidak tersedia. Coba lagi nanti.