# 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:

```
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:

```json
{
  "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](/api).