Kirim email transaksional dari Laravel tanpa mengubah Mailable yang sudah ada

Pasang capimail/capimail-php, ganti MAIL_MAILER, dan Mail::to()->send() di aplikasi Laravel Anda langsung terkirim lewat API dengan idempotency dan webhook.

Tim CapiMailTerbit 4 menit baca
Daftar isi
  1. Yang Anda perlukan
  2. 1. Instal paket
  3. 2. Ganti mailer
  4. 3. Kirim Mailable seperti biasa
  5. Kenapa idempotency key penting di Laravel
  6. 4. Terima status pengiriman lewat webhook
  7. Hal yang perlu diketahui sebelum live
  8. 5. Pindah ke pengiriman live

Aplikasi Laravel biasanya sudah punya Mailable untuk email verifikasi, reset password, dan kuitansi, semuanya dikirim lewat Mail::to()->send(). Paket resmi capimail/capimail-php menambahkan transport capimail ke Laravel, jadi kode itu tetap sama. Yang berubah hanya jalur kirimnya: dari SMTP ke API CapiMail, lengkap dengan idempotency, event pengiriman, dan webhook bertanda tangan.

Yang Anda perlukan

  • Laravel 10, 11, atau 12 dengan PHP 8.1 ke atas.
  • Akun CapiMail dan key uji (cm_test_) dari Dashboard > API Keys. Key uji menjalankan seluruh alur tanpa mengirim email dan tanpa memakai kredit.
  • Untuk kirim live: domain pengirim yang sudah terverifikasi, organisasi yang sudah disetujui, dan key cm_live_.

1. Instal paket

bash
composer require capimail/capimail-php

Service provider dan facade CapiMail terdaftar otomatis lewat package discovery, jadi tidak ada yang perlu ditambahkan ke config/app.php. Kode sumbernya publik di GitHub dan paketnya ada di Packagist.

2. Ganti mailer

Tambahkan key dan alamat pengirim di .env, lalu jadikan capimail sebagai mailer default:

.env· dotenv
CAPIMAIL_API_KEY=cm_test_xxxxxxxx
MAIL_MAILER=capimail
MAIL_FROM_ADDRESS=halo@domain-anda.co.id
MAIL_FROM_NAME="Toko Contoh"

Lalu daftarkan mailer-nya di config/mail.php:

config/mail.php· php
'mailers' => [
    // ...
    'capimail' => [
        'transport' => 'capimail',
    ],
],

Sampai di sini, setiap Mail::to()->send(), notifikasi lewat channel mail, dan email yang diantrekan sudah terkirim lewat POST /api/v1/emails. Selama key yang dipakai masih cm_test_, tidak ada email yang benar-benar keluar, tetapi Anda tetap mendapat message_id dan event simulasi untuk diuji.

3. Kirim Mailable seperti biasa

Mailable yang sudah ada tidak perlu diubah. Satu tambahan yang sangat disarankan adalah header X-CapiMail-Idempotency-Key yang diambil dari id record Anda sendiri:

app/Mail/PesananDikirim.php· php
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Mail\Mailables\Headers;

class PesananDikirim extends Mailable
{
    public function __construct(public \App\Models\Order $order) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: "Pesanan {$this->order->number} sudah dikirim",
            metadata: ['order_id' => (string) $this->order->id], // menjadi tags di CapiMail
        );
    }

    public function content(): Content
    {
        return new Content(view: 'mail.pesanan-dikirim', text: 'mail.pesanan-dikirim-text');
    }

    public function headers(): Headers
    {
        return new Headers(text: [
            'X-CapiMail-Idempotency-Key' => "pesanan-dikirim-{$this->order->id}",
        ]);
    }
}
php
use App\Mail\PesananDikirim;
use Illuminate\Support\Facades\Mail;

Mail::to($order->customer_email)->send(new PesananDikirim($order));

Kenapa idempotency key penting di Laravel

Email di Laravel sering dikirim lewat queue, dan queue mencoba ulang job yang gagal. Tanpa pengaman, satu job yang di-retry bisa berarti dua email kuitansi untuk pelanggan yang sama. Dengan X-CapiMail-Idempotency-Key, request yang diulang dengan key yang sama tetap dihitung satu email dan satu kredit.

Kalau header itu tidak diisi, transport membuat key sendiri dari isi pesan (pengirim, penerima, subjek, isi, dan lampiran) ditambah jendela waktu satu jam (CAPIMAIL_MAIL_IDEMPOTENCY_WINDOW, default 3600 detik). Ini cukup untuk retry yang cepat, tetapi retry yang melewati batas jendela bisa terkirim dua kali. Key dari id record Anda sendiri tidak punya kelemahan itu.

4. Terima status pengiriman lewat webhook

Respons 202 berarti email masuk antrean, belum berarti sampai. Status sebenarnya (terkirim, bounce, komplain) datang dari event penyedia. Paket ini menyediakan route yang sudah memverifikasi tanda tangan dan bebas CSRF:

.env· dotenv
CAPIMAIL_WEBHOOK_SECRET=whsec_xxxxxxxx
routes/web.php· php
Route::capimailWebhook('webhooks/capimail');
php
use CapiMail\Laravel\Events\CapiMailWebhookReceived;
use Illuminate\Support\Facades\Event;

Event::listen(function (CapiMailWebhookReceived $event) {
    // Event bisa dikirim ulang: simpan $event->eventId dan abaikan yang sudah diproses.
    if ($event->type === 'email.bounced') {
        // tandai alamat ini, cari pesannya lewat $event->data['message_id']
    }
});

Tanda tangan yang tidak valid ditolak dengan 400, dan secret yang belum diisi membuat route menolak semua request (fail closed). Penjelasan jenis event ada di panduan webhook status pengiriman.

Hal yang perlu diketahui sebelum live

  • Hanya email transaksional. API ini untuk verifikasi, OTP, reset password, kuitansi, dan notifikasi akun. Header list dan konten pemasaran ditolak dengan 422. Newsletter memakai alur kampanye terpisah, lihat perbedaan email transaksional dan marketing.
  • To dan Cc digabung, maksimal 50 alamat unik per pesan.
  • Setiap alamat Bcc menjadi kiriman sendiri, supaya alamatnya tidak terlihat penerima lain. Artinya setiap Bcc memakai satu kredit, dan jumlahnya dibatasi CAPIMAIL_MAIL_MAX_BCC (default 50).
  • Header kustom lain dibuang. Yang diteruskan hanya List-Unsubscribe, List-Unsubscribe-Post, X-Campaign-Id, X-Entity-Ref-Id, dan header idempotency.
  • Error API muncul sebagai `TransportException`, dengan CapiMailException sebagai penyebabnya, jadi penanganan error Laravel yang sudah ada tetap jalan.

5. Pindah ke pengiriman live

  1. Verifikasi domain pengirim: publikasikan record SPF, DKIM, dan DMARC. Langkahnya ada di panduan SPF, DKIM, dan DMARC.
  2. Tunggu persetujuan organisasi. Selama menunggu, key uji tetap bisa dipakai untuk integrasi.
  3. Buat key cm_live_ dan ganti nilai CAPIMAIL_API_KEY di environment production. Tidak ada kode yang perlu diubah.

Referensi lengkap pemetaan field dan opsi mailer ada di contoh Laravel di dokumentasi.

Pertanyaan yang sering diajukan

Apakah saya harus menulis ulang Mailable yang sudah ada?

Tidak. Cukup ganti MAIL_MAILER ke capimail dan daftarkan mailer-nya di config/mail.php. Menambahkan header X-CapiMail-Idempotency-Key sangat disarankan, tetapi tidak wajib.

Bisakah satu aplikasi memakai dua workspace CapiMail?

Bisa. Tambahkan mailer kedua di config/mail.php dengan opsi 'key' => env('CAPIMAIL_OTHER_KEY'), lalu kirim lewat Mail::mailer('nama-mailer').

Apakah paket ini bisa dipakai tanpa Laravel?

Bisa. Untuk PHP biasa, buat client dengan new CapiMail\CapiMail($apiKey) lalu panggil emails()->send() dengan field API seperti from, to, subject, html, dan idempotency_key.

Semua artikel