Copy page

Integrasi

Integrasi Email

Integrasi Email

Saluran email OmniStream memperlakukan email masuk dan keluar seperti pesan percakapan biasa. Email keluar dikirim melalui SMTP menggunakan library lettre dengan rustls-tls; email masuk diterima melalui webhook dari relay email (misalnya SendGrid Inbound Parse) ke webhook-ingestor.

Peran: Hanya Admin yang dapat menambah atau mengubah integrasi email. Rute frontend: /integrations

Prasyarat

1. Server SMTP yang dapat dijangkau dari host OmniStream. Untuk development, docker compose menyediakan Mailpit di mailpit:1025.
2. Alamat email pengirim (SMTP_FROM_ADDRESS) yang sudah diverifikasi pada provider Anda.
3. (Opsional) Sebuah relay email masuk yang bisa memposting JSON ke URL webhook OmniStream (misalnya SendGrid Inbound Parse dalam mode JSON).

Variabel lingkungan

Semua variabel berikut berasal dari bagian Email (SMTP) pada .env.example:

Variabel	Default	Kegunaan
SMTP_HOST	mailpit	Host SMTP. Kosongkan untuk menonaktifkan saluran email.
SMTP_PORT	1025	Port SMTP. 1025 untuk Mailpit, 587 untuk STARTTLS umum, 465 untuk TLS implisit.
SMTP_USERNAME	(kosong)	Nama pengguna SMTP. Kosongkan jika server tidak menuntut autentikasi (Mailpit).
SMTP_PASSWORD	(kosong)	Kata sandi SMTP.
SMTP_FROM_ADDRESS	noreply@omnistream.local	Alamat From pada email keluar.
SMTP_ENCRYPTION	none	Mode enkripsi: none (plain, untuk Mailpit), starttls (default produksi), tls (implicit TLS, port 465).
EMAIL_WEBHOOK_SECRET	(kosong)	Shared secret untuk memverifikasi HMAC pada webhook email masuk (header X-Email-Webhook-Signature). Jika kosong, verifikasi dilewati.

Mode enkripsi yang valid dikenali message-sender adalah none, starttls, dan tls. Nilai selain itu akan ditolak saat layanan start.

Langkah-langkah (development dengan Mailpit)

1. Jalankan infrastruktur dengan docker compose up -d — ini memunculkan Mailpit pada SMTP 1025 dan web UI http://localhost:8025.
2. Pastikan .env berisi default dev:

   Code
   SMTP_HOST=mailpit
   SMTP_PORT=1025
   SMTP_FROM_ADDRESS=noreply@omnistream.local
   SMTP_ENCRYPTION=none

3. Buka OmniStream sebagai admin → Integrations → tab Email.
4. Isi field SMTP (UI akan memprapopulasi dari .env pertama kali), klik Save.
5. Tunggu hingga 30 detik untuk hot-reload.
6. Dari UI, pilih satu kontak dan kirim email uji. Buka http://localhost:8025 — email akan muncul di Mailpit.

Langkah-langkah (produksi dengan SMTP eksternal)

1. Siapkan akun pada provider Anda (SendGrid, Amazon SES, Mailgun, dsb.). Verifikasi domain pengirim sesuai ketentuan masing-masing.
2. Dapatkan kredensial SMTP — biasanya host, port, username, dan password.
3. Isi .env pada server OmniStream:

   Code
   SMTP_HOST=smtp.sendgrid.net
   SMTP_PORT=587
   SMTP_USERNAME=apikey
   SMTP_PASSWORD=SG.xxxxxxxxxxxx
   SMTP_FROM_ADDRESS=support@omnistream.example.com
   SMTP_ENCRYPTION=starttls

4. Restart message-sender satu kali agar nilai baru dari .env termuat.
5. Di UI Integrations, buka tab Email, verifikasi nilai yang ditampilkan (rahasia akan muncul sebagai placeholder bintang setelah disimpan), klik Save.
6. Kirim email uji ke kontak dan verifikasi pengirimannya melalui dashboard provider.

Catatan TLS: Semua HTTP client OmniStream memakai rustls (bukan native-tls). Provider SMTP harus menyajikan sertifikat yang dapat divalidasi oleh trust store bawaan rustls. Sertifikat self-signed memerlukan konfigurasi tambahan dan tidak didukung out-of-the-box.

Webhook email masuk

OmniStream menerima email masuk sebagai JSON melalui:

Code
POST /webhook/email
Host: <host-webhook-ingestor>
Content-Type: application/json
X-Email-Webhook-Signature: <hex HMAC-SHA256 opsional>

webhook-ingestor — satu binary yang mendengarkan di WEBHOOK_INGESTOR_PORT (default 3001 di local dev), port yang sama dipakai bersama oleh rute WhatsApp, Instagram, Messenger, dan Email — memanggil signature::verify_email_signature untuk memvalidasi tanda tangan. Validasi dilewati jika EMAIL_WEBHOOK_SECRET kosong — berguna untuk uji coba lokal, tetapi tidak disarankan untuk produksi.

Payload minimum harus memuat field from. Contoh payload gaya SendGrid Inbound Parse:

Code
{
  "from": "customer@example.com",
  "to": "support@omnistream.example.com",
  "subject": "Pertanyaan tentang pesanan",
  "text": "Halo, saya ingin menanyakan status pesanan saya...",
  "html": "<p>Halo, saya ingin menanyakan status pesanan saya...</p>"
}

Mengaktifkan EMAIL_WEBHOOK_SECRET

1. Pilih shared secret acak (misal 32 karakter).
2. Setel EMAIL_WEBHOOK_SECRET=<nilai> di .env server OmniStream atau isi kolom email_webhook_secret pada config integrasi email lewat UI. Nilai dari DB akan menggantikan .env melalui hot-reload 30 detik.
3. Konfigurasi relay email Anda untuk menandatangani body dengan HMAC-SHA256 hex memakai secret yang sama dan meletakkannya pada header X-Email-Webhook-Signature.
4. Kirim email uji; periksa log webhook-ingestor. Jika Anda melihat InvalidSignature, secret tidak cocok atau algoritma tanda tangan tidak sesuai.

Mengatur relay (SendGrid Inbound Parse)

1. Di SendGrid, buka Settings → Inbound Parse → Add Host & URL.
2. Tentukan subdomain MX (misalnya parse.omnistream.example.com) dan arahkan rekam MX ke SendGrid.
3. Masukkan URL: https://<host-omnistream>/webhook/email
4. Centang POST the raw, full MIME message dinonaktifkan (kami memakai mode JSON).
5. Centang Check incoming emails for spam sesuai kebijakan Anda.
6. Jika Anda memakai EMAIL_WEBHOOK_SECRET, aktifkan fitur signing yang setara atau gunakan middleware reverse proxy untuk menambah header tanda tangan.

Troubleshooting

• SMTP encryption mode must be 'none', 'starttls', or 'tls' — nilai SMTP_ENCRYPTION salah. Gunakan salah satu dari tiga nilai itu, huruf kecil.
• Connection refused pada Mailpit — pastikan layanan Mailpit jalan (docker compose ps mailpit).
• Email keluar terkirim tetapi ditolak provider — SMTP_FROM_ADDRESS belum diverifikasi di provider. Selesaikan verifikasi domain SPF/DKIM sebelum mencoba lagi.
• Webhook masuk mengembalikan 400 Missing required field 'from' — payload relay tidak memakai mode JSON atau struktur field-nya berbeda. Uji dengan curl + payload contoh di atas untuk memastikan endpoint bekerja.
• Webhook masuk 401 InvalidSignature — EMAIL_WEBHOOK_SECRET di .env atau DB berbeda dari secret yang dipakai relay.

Hubungan dengan API Reference

Endpoint REST untuk mengelola integrasi email tersedia di bawah tag Integrations pada API Reference. Untuk detail webhook masuk email, lihat Developer → Webhook → Inbound Email.