# Gmail Gateway

Gmail Gateway API APIPedia: Kirim email transaksional lewat akun Gmail dengan template dan pelacakan status pengiriman. Panggil dengan satu token API di `https://api.apipedia.id/v1/toolkits/gmail`.

Kirim email verifikasi, invoice, dan notifikasi lewat akun Gmail yang sudah kamu hubungkan. Termasuk template variabel, lampiran, serta webhook untuk status terkirim, gagal, dan dibuka. Pemanggil selalu memanggil API APIPedia dengan token APIPedia sendiri; Composio hanya broker OAuth di belakang layar.

- Base URL: `https://api.apipedia.id/v1/toolkits/gmail`
- Autentikasi: `Authorization: Bearer apk_…` (token dari console.apipedia.id)
- Kategori: Messaging
- Halaman: https://apipedia.id/docs/gmail-gateway
- OpenAPI: https://console.apipedia.id/openapi/gmail-gateway.yaml

Semua respons memakai amplop `{ "is_success", "message", "data" }` kecuali disebutkan lain. Kode error umum: lihat https://apipedia.id/docs#kode-status-error.

## Endpoint (2)

- `GET /messages/{id}`: Ambil isi satu email Gmail
- `POST /send`: Kirim email lewat akun Gmail yang terhubung

### Ambil isi satu email Gmail

`GET https://api.apipedia.id/v1/toolkits/gmail/messages/{id}`

Dieksekusi lewat tool Composio `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID`. Dipakai setelah `GET /toolkits/gmail/messages`, yang sengaja hanya memulangkan metadata supaya responsnya tetap kecil.

| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
| `id` | path | string | ya | `messageId` Gmail dari daftar email. |

Contoh request:

```bash
curl -X GET "https://api.apipedia.id/v1/toolkits/gmail/messages/1925f3c2a7b4e8d1" \
  -H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
```

Contoh respons (200):

```json
{
  "is_success": true,
  "message": "Email content retrieved",
  "data": {
    "tool": "GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID",
    "result": {
      "messageId": "1925f3c2a7b4e8d1",
      "threadId": "1925f3c2a7b4e8d1",
      "subject": "Tagihan September",
      "sender": "billing@contoh.com",
      "messageText": "Tagihan Anda untuk periode September sudah tersedia.",
      "messageTimestamp": "2026-09-30T02:11:00Z"
    }
  }
}
```

### Kirim email lewat akun Gmail yang terhubung

`POST https://api.apipedia.id/v1/toolkits/gmail/send`

Mengirim email lewat akun Google yang sudah dihubungkan di halaman Koneksi (toolkit `gmail`), dieksekusi lewat tool Composio `GMAIL_SEND_EMAIL`. Field `result` pada data berisi jawaban Gmail apa adanya.

Field body: `to` (wajib, alias `recipient_email`), `subject` (wajib), `body` (wajib kecuali `html` diisi; alias `text`), `html` (isi HTML, otomatis `is_html: true`), `is_html` (boolean, opsional), `cc` dan `bcc` (array alamat email).

Lampiran lewat `attachments` (array) atau `attachment` (satu objek): `filename` wajib, `mimetype` opsional (default application/octet-stream), `content` base64 (data URL juga diterima). Gmail hanya menerima SATU lampiran per pengiriman, maksimal 20 MB.

Error: 400 field wajib kosong/alamat tidak valid/lampiran lebih dari satu, 409 akun Gmail belum dihubungkan, 503 COMPOSIO_API_KEY server kosong, 502 Gmail menolak. Efek samping nyata: email benar-benar terkirim.

Body (`application/json`, wajib):

```json
{
  "to": "pelanggan@contoh.com",
  "subject": "Invoice #INV-2026-0913",
  "body": "Halo Budi, total tagihan kamu Rp 25.000.",
  "cc": [
    "keuangan@contoh.com"
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "mimetype": "application/pdf",
      "content": "JVBERi0xLjQKJ..."
    }
  ]
}
```

Contoh request:

```bash
curl -X POST "https://api.apipedia.id/v1/toolkits/gmail/send" \
  -H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"pelanggan@contoh.com","subject":"Invoice #INV-2026-0913","body":"Halo Budi, total tagihan kamu Rp 25.000.","cc":["keuangan@contoh.com"],"attachments":[{"filename":"invoice.pdf","mimetype":"application/pdf","content":"JVBERi0xLjQKJ..."}]}'
```

Contoh respons (200):

```json
{
  "is_success": true,
  "message": "Email sent via the connected Gmail account",
  "data": {
    "tool": "GMAIL_SEND_EMAIL",
    "result": {
      "id": "1925f3c2a7b4e8d1",
      "threadId": "1925f3c2a7b4e8d1",
      "labelIds": [
        "SENT"
      ]
    }
  }
}
```
