Mengirim email melalui SMTP

Jika aplikasi Anda sudah mendukung SMTP, arahkan ke relay kami dengan mengubah host, port, dan kredensialnya. Framework, sistem manajemen konten, printer, dan perangkat lunak lain yang dapat mengirimkan email ke relay SMTP dapat menggunakan jalur ini.

Email yang dikirim melalui SMTP diperlakukan persis seperti email yang dikirim melalui email API: verifikasi domain, IP pool, penandatanganan DKIM, penanganan supresi, pelacakan, event, dan analitik yang sama. SMTP adalah jalur masuk kedua ke produk yang sama, sehingga semua yang Anda atur untuk satu jalur berlaku juga untuk yang lain.

Pilih layanan relay SMTP jika Anda ingin mempertahankan kode pembuatan pesan yang sudah ada di aplikasi Anda. Pilih email API jika Anda membutuhkan field request terstruktur atau template tersimpan. SMTP mengambil konten dari pesan MIME dan opsi pengiriman dari konfigurasi kunci API.

Yang Anda butuhkan terlebih dahulu

Domain pengirim yang terverifikasi. Alamat yang Anda masukkan di MAIL FROM (dan header From pesan) harus milik domain yang sudah Anda verifikasi di workspace ini. Lihat Domain pengirim.
Kunci API dengan scope emails. SMTP menggunakan kunci API biasa Anda dan tidak memerlukan kredensial SMTP terpisah. Buat kunci di Developers > Kunci API dengan pengiriman email diaktifkan. Kunci tanpa scope emails tidak dapat mengirim, begitu juga kunci khusus verify.

Pengaturan koneksi

Arahkan klien Anda ke host SMTP untuk region kunci Anda. Region adalah prefiks di kunci itu sendiri: kunci bk_eu1_... mengirim melalui host eu1, kunci bk_us1_... melalui us1. Autentikasi dengan kunci dari region lain gagal dengan balasan 535 yang menyebutkan host yang harus digunakan.

Region	Host
EU	eu1.smtp.bird.com
US	us1.smtp.bird.com

Port	Enkripsi
465	TLS implisit (SMTPS)
587	STARTTLS
2525	STARTTLS

Gunakan port mana pun yang didukung klien Anda:

Port 465, TLS implisit (SMTPS). Koneksi dienkripsi sejak byte pertama, sebelum perintah apa pun dikirim. Di sebagian besar library, ini adalah opsi "SSL/TLS" atau "SMTPS".
Port 587 dan 2525, STARTTLS. Koneksi dibuka dalam plaintext dan di-upgrade ke TLS dengan perintah STARTTLS sebelum autentikasi. Ini adalah opsi "STARTTLS", terkadang diberi label "TLS" saja. Pilih 2525 jika jaringan Anda memblokir 587.

Apa pun pilihannya, sesi dienkripsi sebelum kredensial Anda dikirim, sehingga tidak pernah dikirim tanpa enkripsi: pada port 587 dan 2525, AUTH ditolak hingga STARTTLS selesai dijalankan. Port 25 tidak tersedia untuk pengiriman.

Autentikasi

Lakukan autentikasi dengan AUTH PLAIN atau AUTH LOGIN. Username adalah string literal bird, dan password adalah kunci API Anda:

Contoh kode

Username: bird
Password: bk_eu1_your_api_key

Username adalah literal tetap dan tidak memiliki identitas tersendiri. Kunci API di field password-lah yang melakukan autentikasi. Di sebagian besar alat SMTP, Anda menempelkan kunci API ke field password dan mengatur username ke bird. Mencabut kunci memutus pengiriman SMTP-nya dalam hitungan detik, termasuk koneksi yang sedang berjalan.

Apa yang berasal dari pesan, dan apa yang berasal dari konfigurasi kunci

Semua yang memiliki tempat alami dalam pesan MIME berasal dari pesan itu sendiri: header From, To, Cc, dan Reply-To, subjek, body HTML dan teks, serta lampiran dan gambar inline. Penerima diambil dari envelope SMTP (RCPT TO). Alamat di RCPT TO yang tidak ada di header To atau Cc yang terlihat diperlakukan sebagai Bcc. Satu pesan dapat memiliki maksimal 50 penerima gabungan to, cc, dan bcc, dan ukuran total pesan dibatasi 20 MB.

Opsi pengiriman yang tidak memiliki tempat standar dalam pesan MIME berasal dari konfigurasi SMTP kunci. Ini mencakup IP pool, kategori, tag, serta pelacakan open dan click. Kunci yang belum dikonfigurasi menggunakan pool default organisasi Anda, kategori transactional, dan pelacakan aktif. Konfigurasikan kunci di Email > SMTP, atau panggil konfigurasi SMTP API. Berikan setiap aplikasi kunci sendiri jika membutuhkan default yang berbeda. Perubahan berlaku untuk pesan baru tanpa perlu menyambungkan ulang klien.

Sesi lengkap

Pada port 465, klien membuka koneksi TLS terlebih dahulu, lalu menjalankan seluruh dialog SMTP di dalamnya:

Contoh kode

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

Pada port 587 atau 2525, klien terhubung dalam plaintext, mengirim STARTTLS untuk meng-upgrade koneksi, lalu menjalankan dialog yang sama di dalam TLS. AUTH tidak ditawarkan hingga upgrade selesai:

Contoh kode

S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

250 terakhir mengembalikan ID pesan yang diantrikan, yaitu ID em_... yang sama dengan yang Anda dapatkan dari API. Anda dapat mencari pesan berdasarkan ID tersebut di Email log atau melalui GET /v1/email/messages/{message_id}.

Mencoba ulang dengan aman

Pipeline menerima pesan dan mengirimkannya secara asinkron, dan klien SMTP mencoba ulang secara agresif saat koneksi terputus. Agar percobaan ulang aman, tambahkan header X-Bird-Idempotency-Key ke pesan: pengulangan dalam jendela retensi mengembalikan ID pesan yang sudah diantrikan alih-alih mengirim salinan kedua. Gunakan nilai yang stabil untuk pesan logis tersebut, seperti ID pesanan atau ID notifikasi. Hindari membuat nilai acak untuk setiap percobaan.

Simpan ID pesan yang diantrikan bersama event aplikasi yang memicu pengiriman. Jika koneksi terputus sebelum Anda menerima balasan akhir, coba lagi pesan logis tersebut dengan kunci yang sama. Setelah jendela retensi, percobaan ulang dapat membuat pesan baru. Pertahankan catatan pengiriman Anda sendiri untuk pemulihan di luar jendela tersebut.

Batas koneksi

Setiap organisasi dapat menampung hingga 10 koneksi SMTP teautentikasi secara bersamaan secara default. Koneksi dihitung sejak autentikasi hingga ditutup, di semua server dan kunci API dalam organisasi. Saat batas tercapai, koneksi tambahan menerima respons transien 421 setelah autentikasi. Gunakan ulang koneksi, kurangi konkurensi, dan coba lagi. Batas ini menghitung koneksi terbuka secara independen dari volume pesan. Email > SMTP menampilkan koneksi aktif terhadap batas.

Sesuaikan ukuran connection pool Anda dengan batas koneksi organisasi. Atur kecepatan pengiriman sesuai kuota kirim. Header pembatasan laju permintaan HTTP mendeskripsikan permintaan API; header tersebut bukan jatah kecepatan kirim SMTP.

Menangani respons SMTP

SMTP melaporkan domain pengirim yang belum diverifikasi, domain penerima yang dicadangkan, IP pool yang tidak dapat digunakan, tipe lampiran yang diblokir, atau pesan yang salah format dengan respons permanen 550. Pesan yang melebihi batas 20 MB mengembalikan 552. Kuota kirim yang terlampaui atau jumlah penerima lebih dari 50 mengembalikan respons transien 452. Penerima yang disupresi ditangani secara asinkron: SMTP menerima pesan, lalu setiap penerima yang disupresi muncul sebagai rejected di email log dan event.

Untuk keputusan antarmuka, bandingkan pengiriman dan pemulihan SMTP dan HTTP. Kedua jalur mengantrikan pekerjaan sebelum pengiriman ke penerima. Event email.delivered mencatat penerimaan oleh server penerima. Event tersebut tidak menjamin penempatan di kotak masuk.

Langkah selanjutnya

Domain pengirim: verifikasi domain yang akan Anda gunakan untuk mengirim.
IP dan pool dedikasi: pilih pool mana yang digunakan kunci untuk mengirim.
Supresi: mengapa penerima yang diterima mungkin tidak menerima pesan.
Email log: temukan pesan berdasarkan ID yang dikembalikan SMTP.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Jelajahi kemampuannyaSMTP relay