Referensi API

REST API AgentSend. Semua request dan respons menggunakan JSON. Base URL: https://api.agentsend.io.

Ikhtisar

AgentSend API adalah REST API yang memberi agen Anda akses pemrograman ke kotak masuk, pesan, utas, webhook, domain, lampiran, dan pengaturan akun. Setiap body request dan respons adalah JSON.

Semua endpoint API tersedia di bawah base URL:

base url

https://api.agentsend.io

ⓘ

Untuk pengembangan lokal, API tersedia di http://localhost:3000 saat menjalankan server secara lokal.

Autentikasi

AgentSend API mendukung dua metode autentikasi. Anda hanya perlu satu per request.

Bearer Token

Teruskan kunci API Anda sebagai token Bearer di header Authorization. Ini adalah metode yang lebih disukai untuk request sisi server.

curl

curl https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>"

Header Kunci API

Atau, teruskan kunci API Anda langsung di header x-api-key.

curl

curl https://api.agentsend.io/inboxes \
  -H "x-api-key: <your-api-key>"

⚠

Jaga kerahasiaan kunci API Anda. Jangan pernah mengeksposnya di kode sisi klien atau commit ke kontrol versi. Gunakan variabel lingkungan untuk meneruskannya ke aplikasi Anda.

Format Request

Kirim body request sebagai JSON dan sertakan header Content-Type: application/json pada semua request yang memiliki body.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

Paginasi

Endpoint yang mengembalikan daftar mendukung parameter query limit dan offset untuk paginasi. Batas default adalah 20.

Parameter	Tipe	Default	Deskripsi
`limit`	integer	`20`	Jumlah maksimum item yang dikembalikan. Maks 100.
`offset`	integer	`0`	Jumlah item yang dilewati sebelum mengembalikan hasil.

Semua respons daftar menyertakan array data dan jumlah total dari semua catatan yang cocok:

json — paginated response

{
  "data": [ /* array of objects */ ],
  "total": 142
}

Untuk mengambil halaman berikutnya, tambahkan offset dengan nilai limit. Misalnya, untuk mendapatkan halaman 3 dengan ukuran halaman 20: ?limit=20&offset=40.

Penanganan Error

Error mengembalikan body JSON dengan objek error yang berisi code yang dapat dibaca mesin, message yang dapat dibaca manusia, dan status HTTP.

json — error response

{
  "error": {
    "code": "INBOX_NOT_FOUND",
    "message": "No inbox found with that ID.",
    "status": 404
  }
}

Kode status HTTP umum yang dikembalikan oleh API:

Status	Arti
`400`	Bad Request — body request tidak memiliki field yang wajib atau berisi nilai yang tidak valid.
`401`	Unauthorized — tidak ada kunci API yang disediakan, atau kuncinya tidak valid.
`403`	Forbidden — kunci API tidak memiliki izin untuk melakukan tindakan ini.
`404`	Not Found — sumber daya yang diminta tidak ada.
`409`	Conflict — sumber daya sudah ada atau request bertentangan dengan status saat ini.
`429`	Too Many Requests — Anda telah melebihi batas laju Anda. Mundur dan coba lagi.
`500`	Internal Server Error — terjadi kesalahan di sisi AgentSend.

Pembatasan Laju

Semua endpoint API dibatasi lajunya untuk melindungi stabilitas platform. Saat Anda melebihi batas, API mengembalikan respons 429 Too Many Requests.

Setiap respons API menyertakan header batas laju sehingga Anda dapat melacak penggunaan Anda:

Header	Deskripsi
`X-RateLimit-Limit`	Jumlah maksimum request yang diizinkan di jendela saat ini.
`X-RateLimit-Remaining`	Jumlah request yang tersisa di jendela saat ini.
`X-RateLimit-Reset`	Timestamp Unix saat jendela batas laju direset.

💡

Gunakan backoff eksponensial saat mencoba ulang setelah respons 429. Tunggu waktu yang ditunjukkan oleh X-RateLimit-Reset sebelum mengirim request tambahan.

Idempotensi

Request POST dapat menyertakan header Idempotency-Key untuk dengan aman mencoba ulang request tanpa membuat sumber daya duplikat. Jika request dengan kunci idempotensi yang sama diterima dalam jendela idempotensi, respons asli dikembalikan alih-alih membuat sumber daya baru.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-abc123" \
  -d '{"displayName": "Support Agent"}'

Bagian API

Jelajahi referensi lengkap untuk setiap sumber daya:

📩

Kotak Masuk

Buat, perbarui, dan hapus kotak masuk agen. Daftar semua kotak masuk di akun Anda.

✉

Pesan

Kirim email keluar dan daftar pesan yang diterima untuk kotak masuk.

💬

Utas

Daftar dan kelola utas percakapan yang dikelompokkan berdasarkan subjek dan peserta.

🔌

Webhooks

Daftarkan endpoint untuk menerima notifikasi event real-time.

🌐

Domain

Tambahkan domain pengirim kustom dan kelola verifikasi DNS.

⚙

Akun

Ambil detail akun, kelola kunci API, dan lihat penggunaan.

📎

Lampiran

Unggah file dan lampirkan ke pesan keluar.

← Sebelumnya Integrasi Selanjutnya → API: Kotak Masuk