Gunakan artikel ini untuk integrasi HTTP API. Jika ingin memakai konfigurasi SMTP Laravel seperti Brevo, baca artikel khusus SMTP Relay GiMail.

1. Membuat API Key

Masuk ke dashboard GiMail, lalu buka menu API Keys. Buat key baru untuk setiap website atau aplikasi agar penggunaan email mudah dilacak dan dicabut jika diperlukan.

Field yang perlu diisi

• Nama aplikasi: nama website atau sistem yang akan memakai key, misalnya Website LMS.
• Environment: gunakan test untuk percobaan dan live untuk production.
• Allowed domain: opsional, dipakai sebagai catatan domain aplikasi client.
• Allowed IP: opsional, dipakai untuk membatasi request dari IP server tertentu.
• Rate limit: jumlah maksimal request per menit.
• Monthly quota: batas pengiriman bulanan untuk key tersebut.

2. Menyimpan API Key di Website Client

Simpan API key di file environment website client. Jangan pernah menyimpan API key di JavaScript frontend, repository publik, atau halaman HTML.

GIMAIL_API_KEY=gi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GIMAIL_BASE_URL=https://ses.guruinovatif.id

3. Mengirim Request Email

Setiap request dari aplikasi client wajib membawa header Authorization dengan format Bearer token.

POST /api/v1/email/send HTTP/1.1
Host: ses.guruinovatif.id
Authorization: Bearer gi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

Contoh payload reset password

{
  "type": "reset_password",
  "to": "user@example.com",
  "subject": "Reset Password Akun Anda",
  "html": "<p>Klik tombol berikut untuk reset password.</p>",
  "text": "Klik link berikut untuk reset password.",
  "metadata": {
    "user_id": 123,
    "source": "website-lms"
  }
}

4. Tipe Email yang Direkomendasikan

1. reset_password untuk email lupa password.
2. verify_email untuk verifikasi alamat email.
3. otp untuk kode keamanan sementara.
4. notification untuk notifikasi sistem.
5. custom untuk kebutuhan lain.

5. Response API

Jika request berhasil diterima, API akan mengembalikan status sukses dan ID log pengiriman.

{
  "success": true,
  "message": "Email berhasil dikirim.",
  "data": {
    "delivery_id": 101,
    "contact_id": 25,
    "status": "sent"
  }
}

Contoh response gagal

{
  "success": false,
  "message": "API key tidak valid atau sudah dicabut."
}

6. Best Practice Keamanan

• Gunakan API key berbeda untuk setiap aplikasi.
• Gunakan environment test saat development.
• Revoke API key jika dicurigai bocor.
• Batasi rate limit dan quota sesuai kebutuhan aplikasi.
• Simpan API key hanya di server, bukan di browser.

Jika website client berada di server production dengan IP tetap, isi Allowed IP agar request dari lokasi lain bisa ditolak.