Berikut adalah rancangan dokumentasi API yang lengkap, profesional, dan siap Anda serahkan (copy-paste) ke developer rekanan Anda.

Dokumentasi ini mencakup cara autentikasi, struktur request/response, dan contoh integrasi.

---

# Dokumentasi Integrasi Email API (Google Apps Script)

**Versi:** 1.0.0
**Status:** Active
**Base URL:** `[URL_WEB_APP_ANDA]`
*(Catatan: URL didapatkan setelah Anda melakukan "Deploy > New Deployment > Web App" di Google Apps Script Editor)*

## 1. Ikhtisar & Autentikasi

API ini dibangun menggunakan Google Apps Script untuk menangani pengiriman email transaksional dan bulk email. Semua request harus menggunakan format JSON.

### Autentikasi

Setiap request **wajib** menyertakan API Key.

* **API Key:** `rapiin2025`
* **Metode:** Disertakan dalam body JSON (POST) atau parameter URL (GET).

### Batasan (Rate Limits)

* **Maksimal Request:** 500 request per hari (Reset setiap 24 jam).
* **Maksimal Penerima:** 50 penerima (To/CC/BCC) per request.
* **Bulk Email Limit:** Maksimal 10 email object per satu request bulk.

---

## 2. API Endpoints (POST)

Gunakan method `POST` untuk melakukan pengiriman email. Header `Content-Type: application/json` wajib digunakan.

### A. Endpoint: Single Email (`send-email`)

Digunakan untuk mengirim satu email (bisa ke banyak penerima).

**Body Parameter:**

| Field | Tipe | Wajib | Keterangan |
| --- | --- | --- | --- |
| `api_key` | String | **Ya** | Kunci autentikasi. |
| `endpoint` | String | **Ya** | Value: `"send-email"` |
| `to` | String/Array | **Ya** | Alamat email penerima. |
| `subject` | String | **Ya** | Subjek email. |
| `body` | String | **Ya** | Body email (Text version). |
| `html_body` | String | Opsional | Body email (HTML version). Jika ada, ini diprioritaskan. |
| `from_name` | String | Opsional | Nama pengirim (Default: API Mailer). |
| `cc` | String/Array | Opsional | Carbon Copy. |
| `bcc` | String/Array | Opsional | Blind Carbon Copy. |
| `reply_to` | String | Opsional | Alamat Reply-To. |
| `attachments` | Array | Opsional | Array object lampiran (Lihat bagian Attachment Object). |

**Contoh Request (JSON):**

```json
{
  "api_key": "rapiin2025",
  "endpoint": "send-email",
  "to": ["user@example.com", "admin@example.com"],
  "subject": "Laporan Harian",
  "body": "Berikut laporan harian Anda.",
  "html_body": "<h1>Laporan Harian</h1><p>Berikut laporan...</p>",
  "from_name": "Sistem Notifikasi",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "mime_type": "application/pdf",
      "base64_data": "JVBERi0xLjQKJ..."
    }
  ]
}

```

### B. Endpoint: Bulk Email (`bulk-email`)

Digunakan untuk mengirim email yang berbeda ke penerima yang berbeda dalam satu request HTTP.

**Body Parameter:**

| Field | Tipe | Wajib | Keterangan |
| --- | --- | --- | --- |
| `api_key` | String | **Ya** | Kunci autentikasi. |
| `endpoint` | String | **Ya** | Value: `"bulk-email"` |
| `emails` | Array | **Ya** | Array berisi object email (Max 10 item). |

**Struktur Object dalam Array `emails`:**
Sama seperti parameter Single Email (`to`, `subject`, `body`, dll).

**Contoh Request (JSON):**

```json
{
  "api_key": "rapiin2025",
  "endpoint": "bulk-email",
  "emails": [
    {
      "to": "client1@example.com",
      "subject": "Tagihan #001",
      "body": "Halo Client 1..."
    },
    {
      "to": "client2@example.com",
      "subject": "Tagihan #002",
      "body": "Halo Client 2..."
    }
  ]
}

```

---

## 3. Struktur Object Attachment

Sistem mendukung dua metode lampiran: Mengambil dari Google Drive atau mengirim Base64 string.

**Opsi 1: Base64 (Upload file langsung)**

```json
{
  "filename": "laporan.pdf",
  "mime_type": "application/pdf",
  "base64_data": "BASE64_STRING_HERE"
}

```

**Opsi 2: Google Drive File**
Pastikan akun Google script memiliki akses ke file tersebut.

```json
{
  "drive_file_id": "1A2B3C4D5E6F..."
}

```

---

## 4. API Endpoints (GET) - Monitoring

Gunakan method `GET` untuk pengecekan sistem.

| Path | Parameter | Deskripsi |
| --- | --- | --- |
| `/` | `?path=health` | Cek status kesehatan server (Uptime). |
| `/` | `?path=usage` | Cek statistik penggunaan kuota hari ini. |
| `/` | `?path=logs&api_key=...` | Melihat log aktivitas terakhir (Perlu API Key). |

**Contoh URL:**
`https://script.google.com/.../exec?path=usage`

---

## 5. Response Standar

API akan selalu mengembalikan response dengan format JSON berikut:

**Sukses (HTTP 200):**

```json
{
  "success": true,
  "data": {
    "messageId": "msg_170425...",
    "processing_time_ms": 150
  },
  "meta": {
    "version": "1.0.0",
    "timestamp": "2025-01-03T04:00:00.000Z"
  }
}

```

**Gagal (HTTP 4xx / 5xx):**

```json
{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "details": "Please provide a valid API key"
  }
}

```

---

## 6. Contoh Kode Integrasi (Node.js / Axios)

Berikut adalah contoh cara memanggil API ini menggunakan Node.js:

```javascript
const axios = require('axios');

const API_URL = 'https://script.google.com/macros/s/[DEPLOYMENT_ID]/exec';
const API_KEY = 'rapiin2025';

async function sendEmail() {
  try {
    const payload = {
      api_key: API_KEY,
      endpoint: 'send-email', // Wajib diset manual karena redirect GAS bisa menghilangkan parameter
      to: 'customer@gmail.com',
      subject: 'Test Integrasi',
      body: 'Email ini dikirim dari Node.js',
      html_body: '<b>Email ini dikirim dari Node.js</b>',
      from_name: 'Admin Toko'
    };

    // Google Apps Script sering melakukan redirect (302), pastikan client mengikuti redirect
    const response = await axios.post(API_URL, payload, {
      headers: { 'Content-Type': 'application/json' },
      maxRedirects: 5
    });

    console.log('Sukses:', response.data);
  } catch (error) {
    console.error('Gagal:', error.response ? error.response.data : error.message);
  }
}

sendEmail();

```

---

### Catatan Penting untuk Developer

1. **CORS:** Google Apps Script tidak mendukung CORS preflight standar untuk browser-side AJAX call secara langsung. Disarankan memanggil API ini dari **Backend Server** (Node.js, PHP, Python, dll).
2. **Redirects:** Saat melakukan request POST ke Web App URL (`/exec`), Google akan meredirect ke URL sementara (`googleusercontent.com`). Pastikan HTTP Client Anda dikonfigurasi untuk **Follow Redirects**.
3. **Logs:** Semua aktivitas tercatat di Google Sheet dengan ID: `1994KuhHCUUJotc_YCLy2ALPCNC-PPLrA8xYIT0SSHsQ`.

---

**Next Step yang bisa saya lakukan untuk Anda:**
Apakah Anda ingin saya buatkan juga contoh file `.json` (Postman Collection) agar developer Anda bisa langsung *import* dan *test* API ini tanpa coding manual?