Kotak Masuk

Buat dan kelola kotak masuk email untuk agen AI Anda. Setiap kotak masuk mendapat alamat email unik yang dapat mengirim dan menerima pesan.

ℹ

Semua request API memerlukan header x-api-key. Dapatkan kunci Anda dari dasbor. Base URL untuk semua endpoint adalah https://api.agentsend.io.

Objek Inbox

Semua endpoint yang mengembalikan inbox akan menyertakan field berikut.

Field	Tipe	Deskripsi
`id`	uuid	Pengenal unik untuk kotak masuk.
`address`	string	Alamat email lengkap yang ditetapkan ke kotak masuk ini, misalnya `a1b2c3@agentsend.io`.
`displayName`	string	Nama yang dapat dibaca manusia yang ditampilkan di header From saat mengirim email.
`domainId`	uuid \| null	ID dari domain kustom yang diverifikasi, atau `null` saat menggunakan domain AgentSend bersama.
`status`	string	Salah satu dari `active`, `suspended`, atau `deleted`.
`dailySendLimit`	integer	Jumlah maksimum pesan yang dapat dikirim kotak masuk ini per hari kalender.
`sendsToday`	integer	Jumlah pesan yang dikirim hari ini (direset pada tengah malam UTC).
`totalSent`	integer	Jumlah kumulatif semua pesan yang dikirim dari kotak masuk ini.
`bounceCount`	integer	Jumlah hard bounce yang tercatat terhadap kotak masuk ini.
`complaintCount`	integer	Jumlah keluhan spam yang tercatat terhadap kotak masuk ini.
`createdAt`	string (ISO 8601)	Timestamp saat kotak masuk dibuat.

Inbox object

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 12,
  "totalSent": 1847,
  "bounceCount": 2,
  "complaintCount": 0,
  "createdAt": "2025-03-15T10:22:00Z"
}

Buat kotak masuk

POST /inboxes

Menyediakan kotak masuk baru dan menetapkan alamat email. Jika tidak ada address yang disediakan, alamat acak pada domain bersama agentsend.io dihasilkan. Untuk menggunakan domain kustom, teruskan domainId yang diverifikasi.

Body request

Parameter	Tipe	Deskripsi
`address`	string	Alamat email yang diinginkan (local-part saja jika menggunakan domain kustom, atau alamat lengkap). Opsional — dihasilkan otomatis jika dihilangkan.
`displayName`	string	Nama ramah yang ditampilkan di header From. Opsional.
`domainId`	uuid	ID dari domain kustom yang diverifikasi untuk ditetapkan ke kotak masuk ini. Opsional — default ke domain AgentSend bersama.

Mengembalikan

201 Created dengan objek Inbox yang baru dibuat.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

javascript

const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",
  }),
});

const inbox = await res.json(); // 201 Created
console.log(inbox.address); // "a1b2c3@agentsend.io"

Response · 201 Created

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 0,
  "totalSent": 0,
  "bounceCount": 0,
  "complaintCount": 0,
  "createdAt": "2025-04-16T09:00:00Z"
}

Daftar kotak masuk

GET /inboxes

Mengembalikan daftar terpaginasi dari semua kotak masuk di akun Anda, diurutkan berdasarkan tanggal pembuatan (paling baru dulu).

Parameter query

Parameter	Tipe	Default	Deskripsi
`limit`	integer	`20`	Jumlah kotak masuk yang dikembalikan. Maksimum `100`.
`offset`	integer	`0`	Jumlah kotak masuk yang dilewati sebelum mengembalikan hasil. Gunakan dengan `limit` untuk paginasi.

Mengembalikan

200 OK dengan envelope terpaginasi yang berisi array objek Inbox.

curl

curl https://api.agentsend.io/inboxes?limit=10&offset=0 \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const res = await fetch(
  "https://api.agentsend.io/inboxes?limit=10&offset=0",
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data, total, limit, offset } = await res.json();
console.log(`Showing ${data.length} of ${total} inboxes`);

Response · 200 OK

{
  "data": [
    {
      "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
      "address": "a1b2c3@agentsend.io",
      "displayName": "Support Agent",
      "domainId": null,
      "status": "active",
      "dailySendLimit": 500,
      "sendsToday": 12,
      "totalSent": 1847,
      "bounceCount": 2,
      "complaintCount": 0,
      "createdAt": "2025-03-15T10:22:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Ambil kotak masuk

GET /inboxes/{id}

Mengambil satu kotak masuk berdasarkan ID-nya, termasuk penghitung pengiriman langsung dan metrik kesehatan.

Parameter path

Parameter	Tipe	Deskripsi
`id` wajib	uuid	ID kotak masuk untuk diambil.

Mengembalikan

200 OK dengan objek Inbox. Mengembalikan 404 Not Found jika kotak masuk tidak ada atau milik akun berbeda.

curl

curl https://api.agentsend.io/inboxes/3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const inboxId = "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c";

const inbox = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
).then(r => r.json());

console.log(inbox.status);     // "active"
console.log(inbox.sendsToday); // 12

Response · 200 OK

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 12,
  "totalSent": 1847,
  "bounceCount": 2,
  "complaintCount": 0,
  "createdAt": "2025-03-15T10:22:00Z"
}

Hapus kotak masuk

DELETE /inboxes/{id}

Menghapus kotak masuk dan alamat emailnya secara permanen. Semua pesan dan utas yang terkait dengan kotak masuk juga dihapus. Tindakan ini tidak dapat dibatalkan.

⚠

Menghapus kotak masuk tidak dapat dibatalkan. Jika Anda hanya perlu menjeda pengiriman sementara, pertimbangkan field status kotak masuk (hubungi dukungan untuk menangguhkan kotak masuk).

Parameter path

Parameter	Tipe	Deskripsi
`id` wajib	uuid	ID kotak masuk yang akan dihapus.

Mengembalikan

204 No Content saat sukses dengan body respons kosong. Mengembalikan 404 Not Found jika kotak masuk tidak ada atau milik akun berbeda.

curl

curl -X DELETE https://api.agentsend.io/inboxes/3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const inboxId = "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c";

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

// 204 No Content — no body to parse
if (res.ok) console.log("Inbox deleted");

← Sebelumnya Ikhtisar API Selanjutnya → API: Pesan