Copy page

Hubungkan Channel

Integrasi Email

Saluran email OmniStream memperlakukan email masuk dan keluar seperti pesan percakapan biasa. Email keluar dikirim melalui SMTP; email masuk diterima melalui webhook dari relay email (misalnya SendGrid Inbound Parse).

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

Prasyarat

1. Server SMTP yang dapat dijangkau. Untuk development, Mailpit tersedia sebagai server SMTP lokal.
2. Alamat email pengirim 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).

Pengaturan koneksi SMTP

Konfigurasi email diisi melalui UI Integrations (tab Email). Informasi yang dibutuhkan:

Pengaturan	Keterangan
SMTP Host	Host SMTP provider Anda (mis. smtp.sendgrid.net)
SMTP Port	587 untuk STARTTLS, 465 untuk TLS implisit, 1025 untuk Mailpit dev
SMTP Username	Nama pengguna SMTP (kosongkan jika tidak diperlukan)
SMTP Password	Kata sandi SMTP
From Address	Alamat From pada email keluar (mis. support@omnistream.example.com)
Encryption	Mode enkripsi: none, starttls, atau tls
Email Webhook Secret	Shared secret untuk memverifikasi tanda tangan webhook email masuk (opsional)

Langkah-langkah (development dengan Mailpit)

1. Pastikan Mailpit sudah berjalan (biasanya pada port 1025 SMTP dan web UI http://localhost:8025).
2. Buka OmniStream sebagai admin → Integrations → tab Email.
3. Isi field SMTP dengan nilai dev (host: Mailpit, port: 1025, enkripsi: none), klik Save.
4. Tunggu hingga 30 detik untuk konfigurasi aktif.
5. 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. Di UI Integrations, buka tab Email, isi field SMTP sesuai kredensial provider, klik Save.
4. Tunggu hingga 30 detik agar konfigurasi aktif.
5. Kirim email uji ke kontak dan verifikasi pengirimannya melalui dashboard provider.

Catatan TLS: OmniStream mendukung mode enkripsi none, starttls, dan tls. Provider SMTP harus menyajikan sertifikat yang valid. Sertifikat self-signed tidak didukung out-of-the-box.

Webhook email masuk

OmniStream menerima email masuk sebagai JSON melalui:

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

Jika Email Webhook Secret dikonfigurasi, tanda tangan akan divalidasi. Jika kosong, validasi dilewati — 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 (minimal 32 karakter).
2. Isi field Email Webhook Secret pada UI Integrations → tab Email.
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. Jika Anda melihat error InvalidSignature, periksa bahwa secret di kedua sisi sama persis.

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

• Enkripsi tidak valid — nilai mode enkripsi harus salah satu dari: none, starttls, atau tls.
• Connection refused pada Mailpit — pastikan layanan Mailpit sudah berjalan.
• Email keluar terkirim tetapi ditolak provider — alamat pengirim 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.
• Webhook masuk 401 InvalidSignature — Email Webhook Secret di konfigurasi OmniStream berbeda dari secret yang dipakai relay.

Hubungan dengan API Reference

Endpoint REST untuk mengelola integrasi email tersedia di bawah tag Integrations pada API Reference.