Core Mail API: Transport, Pengaturan Pengiriman, dan Email Uji

Jyavani Core menyediakan Mail API sebagai satu jalur pengiriman email untuk fitur CMS dan plugin. Plugin fitur cukup menyerahkan pesan terstruktur kepada Core; pemilihan transport, identitas pengirim, fallback, dan pencatatan pengiriman dikelola terpisah.

Mengapa memakai Mail API

Pemanggilan mail(), SMTP, atau API provider secara langsung dari setiap plugin membuat konfigurasi pengiriman tersebar. Saat provider berubah, setiap plugin harus disesuaikan sendiri. Mail API memisahkan kebutuhan fitur dari cara pesan dikirim.

• Plugin fitur tidak perlu bergantung pada plugin SMTP tertentu.
• Site Owner dapat mengganti transport tanpa mengubah kode pemanggil.
• Validasi pesan, hasil pengiriman, fallback, dan logging memakai kontrak Core yang sama.
• Transport tambahan dapat dipasang atau dinonaktifkan sebagai plugin opsional.

Pengaturan di Settings > Email

Halaman Email Delivery hanya tersedia bagi Site Owner yang memiliki akses pengaturan Core. Halaman ini mengelola:

• Primary transport sebagai jalur pengiriman utama.
• Fallback transport yang dicoba ketika transport utama tidak tersedia atau mengalami kegagalan sementara.
• From name dan From email address sebagai identitas pengirim default.
• Reply-To opsional untuk memisahkan alamat balasan dari alamat pengirim.
• Delivery logging dengan mode off, kegagalan saja, atau seluruh percobaan yang sudah disamarkan.

Transport bawaan native menyerahkan pesan ke mail() milik PHP dan infrastruktur hosting. Kredensial SMTP tidak disimpan oleh halaman Core. Plugin transport menyediakan halaman konfigurasinya sendiri lalu mendaftarkan adapter kepada Mail API.

Mengirim email dari plugin

Plugin fitur memanggil jy_mail_send() dan tidak perlu mengetahui apakah situs memakai native mail, SMTP, atau provider lain.

$result = jy_mail_send($pdo, [
    'to' => ['[email protected]'],
    'subject' => 'Notifikasi Jyavani',
    'body' => 'Proses telah selesai.',
    'content_type' => 'text/plain',
]);

if (!$result['ok']) {
    // Tampilkan pesan umum atau jadwalkan penanganan sesuai fitur.
}

Pesan menerima daftar penerima, subject, body, content type, sender terstruktur, dan Reply-To opsional. Raw header dari pemanggil sengaja tidak diterima. Core menolak alamat atau field header yang mengandung karakter kontrol sebelum transport dijalankan.

Kontrak plugin transport

Plugin adapter mendaftarkan transport melalui jy_mail_register_transport(). Callback menerima pesan yang sudah dinormalisasi dan context pengiriman, kemudian mengembalikan satu status stabil:

• accepted ketika transport menerima tanggung jawab atas pesan.
• temporary_failure untuk kegagalan sementara yang aman dicoba melalui fallback.
• permanent_failure untuk penolakan atau konfigurasi yang tidak boleh diulang melalui fallback.

Core tidak menerima detail provider, kredensial, transcript protokol, atau isi pesan dalam objek hasil. Plugin transport harus menyimpan diagnostik sensitif di luar respons dan tetap menerapkan redaksi.

Fallback yang eksplisit

Fallback hanya berjalan ketika transport utama tidak tersedia, melaporkan kegagalan sementara, atau melempar exception. Penolakan permanen dan kontrak transport yang invalid tidak memicu fallback. Kebijakan ini mengurangi risiko pengiriman ganda ketika provider sudah memproses pesan tetapi koneksi terputus sebelum aplikasi menerima konfirmasi.

Primary dan fallback tidak boleh menunjuk transport yang sama. Bila fallback tidak diperlukan, pilih No fallback agar kegagalan tetap terlihat jelas.

Keamanan dan privasi

• Recipient, sender, Reply-To, subject, body, content type, dan ukuran pesan divalidasi sebelum pengiriman.
• Pesan yang diubah melalui filter dinormalisasi dan divalidasi kembali.
• Plugin tidak dapat mengganti transport bawaan native atau mendaftarkan nama transport yang sama dua kali.
• Log Core hanya mencatat ID, status, code, nama transport, penggunaan fallback, dan jumlah penerima.
• Log tidak memuat alamat penerima, subject, body, kredensial, atau nilai OTP.
• Pengaturan dan email uji dilindungi Site Owner policy, POST, dan CSRF.

Menguji pengiriman

1. Simpan identitas pengirim dan transport di Settings > Email.
2. Jika memakai SMTP atau provider API, selesaikan konfigurasi pada halaman plugin transport.
3. Masukkan satu alamat penerima di panel Send Test Email.
4. Kirim pengujian dan periksa log server atau dashboard provider bila transport tidak menerima pesan.

Email uji dibatasi frekuensinya dan hanya menggunakan subject serta body yang ditentukan server. Status accepted berarti transport menerima pesan, bukan jaminan email masuk ke inbox. Konfigurasikan SPF, DKIM, dan DMARC pada domain pengirim serta periksa reputasi dan kebijakan provider.

Batas fitur saat ini

Kontrak Mail API berfokus pada email transactional sederhana dalam format text/plain atau text/html. CC, BCC, attachment, raw MIME part, dan header bebas belum menjadi bagian dari API. Plugin sebaiknya tidak membuat jalur pengiriman kedua untuk menghindari validasi Core; ajukan perluasan kontrak ketika kebutuhan tersebut memang harus didukung lintas transport.

Dengan pola ini, fitur seperti OTP, notifikasi akun, formulir, atau laporan dapat memakai satu API yang sama. Operasional situs tetap bebas memilih native mail, SMTP, atau provider lain tanpa membuat plugin fitur saling bergantung.