Pesan

Kirim email keluar, daftar pesan di kotak masuk, ambil satu pesan, dan hapus pesan.

ⓘ

Semua request memerlukan header x-api-key. Base URL untuk setiap endpoint adalah https://api.agentsend.io.

Objek Message

Setiap endpoint yang mengembalikan pesan mengembalikan bentuk ini.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Hello from AgentSend",
  "bodyText": "This email was sent by an AI agent.",
  "bodyHtml": "<p>This email was sent by an AI agent.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v...@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Field	Tipe	Deskripsi
`id`	string (uuid)	Pengenal pesan unik.
`inboxId`	string (uuid)	Kotak masuk tempat pesan ini berada.
`threadId`	string (uuid)	Utas tempat pesan ini berada.
`direction`	enum	`outbound` untuk pesan yang dikirim, `inbound` untuk pesan yang diterima.
`fromAddress`	string	Alamat email pengirim.
`toAddresses`	string[]	Alamat email penerima utama.
`ccAddresses`	string[]	Alamat email penerima CC.
`subject`	string	Baris subjek email.
`bodyText`	string \| null	Body teks biasa.
`bodyHtml`	string \| null	Body HTML.
`delivery`	enum	`email` saat AgentSend menyerahkan pesan ke SES, `dry-run` saat lingkungan ini menyimulasikan pengiriman tanpa benar-benar mengirim email.
`status`	enum	Status pengiriman saat ini. Salah satu dari `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received`.
`attachments`	AttachmentMeta[]	Array objek metadata lampiran (id, filename, contentType, size).
`messageIdHeader`	string	Nilai header `Message-ID` RFC 5322.
`createdAt`	string (ISO 8601)	Saat pesan dibuat.

Kirim Pesan

POST /inboxes/{inboxId}/messages

Kirim email keluar dari kotak masuk. Pesan diantre segera dan mengembalikan 202 Accepted bersama dengan objek Message baru. Periksa delivery untuk melihat apakah lingkungan mengirim email nyata (email) atau hanya menyimulasikannya (dry-run). Pembaruan status pengiriman tersedia melalui webhooks atau dengan polling GET /messages/{id}.

Parameter Path

Parameter	Tipe	Deskripsi
`inboxId` wajib	string (uuid)	ID kotak masuk tempat mengirim.

Body Request

Parameter	Tipe	Deskripsi
`to` wajib	string[]	Satu atau lebih alamat email penerima.
`subject` wajib	string	Baris subjek email. Maksimum 998 karakter.
`cc`	string[]	Alamat email penerima CC.
`bcc`	string[]	Alamat email penerima BCC. Alamat BCC tidak terlihat oleh penerima lain.
`bodyText`	string	Body teks biasa. Setidaknya salah satu dari `bodyText` atau `bodyHtml` harus disediakan.
`bodyHtml`	string	Body HTML. AgentSend secara otomatis menghasilkan fallback teks jika hanya HTML yang disediakan.
`threadId`	string (uuid)	Lampirkan pesan ini ke utas yang ada. Jika dihilangkan, utas baru dibuat.
`attachmentIds`	string[] (uuid)	ID lampiran yang telah diunggah sebelumnya untuk disertakan. Unggah file terlebih dahulu melalui API Lampiran.

Contoh Request

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.AGENTSEND_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: ["customer@example.com"],
      cc: ["manager@example.com"],
      subject: "Your order is confirmed",
      bodyText: "Hi, your order #1234 has been confirmed.",
      bodyHtml: "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
      attachmentIds: ["att_01hx9k2v3w4x5y6z7a8b9c0d"],
    }),
  }
);

const message = await res.json();
console.log(message.id, message.status); // "msg_...", "queued"

Respons — 202 Accepted

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": ["manager@example.com"],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "queued",
  "attachments": [
    {
      "id": "att_01hx9k2v3w4x5y6z7a8b9c0d",
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Daftar Pesan

GET /inboxes/{inboxId}/messages

Mengembalikan daftar terpaginasi dari pesan di kotak masuk, diurutkan berdasarkan createdAt menurun. Gunakan filter status untuk mengambil hanya pesan dalam status pengiriman tertentu — misalnya, status=received untuk mengambil pesan masuk yang harus diproses agen Anda.

Parameter Path

Parameter	Tipe	Deskripsi
`inboxId` wajib	string (uuid)	Kotak masuk untuk menampilkan pesan.

Parameter Query

Parameter	Tipe	Deskripsi
`limit`	integer	Jumlah pesan yang dikembalikan. Default `20`. Maksimum `100`.
`offset`	integer	Jumlah pesan yang dilewati untuk paginasi. Default `0`.
`status`	enum	Filter berdasarkan status pengiriman. Salah satu dari `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received`.

Contoh Request

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=50`,
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const { data, total } = await res.json();

for (const msg of data) {
  console.log(msg.fromAddress, msg.subject);
}

Respons — 200 OK

json

{
  "data": [
    {
      "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
      "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
      "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
      "direction": "inbound",
      "fromAddress": "customer@example.com",
      "toAddresses": ["agent@yourdomain.com"],
      "ccAddresses": [],
      "subject": "Re: Your order is confirmed",
      "bodyText": "Thanks! Can I change the delivery address?",
      "bodyHtml": null,
      "status": "received",
      "attachments": [],
      "messageIdHeader": "<abc123@mail.example.com>",
      "createdAt": "2026-04-16T10:45:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Ambil Pesan

GET /messages/{id}

Ambil satu pesan berdasarkan ID-nya. Gunakan ini untuk polling pembaruan status pengiriman setelah mengirim.

Parameter Path

Parameter	Tipe	Deskripsi
`id` wajib	string (uuid)	ID pesan untuk diambil.

Contoh Request

javascript

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

const message = await res.json();
console.log(message.status); // "delivered"

Respons — 200 OK

Mengembalikan satu objek Message.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Hapus Pesan

DELETE /messages/{id}

Menghapus pesan secara permanen. Tindakan ini tidak dapat dibatalkan. Menghapus pesan tidak membatalkan pengirimannya — jika email sudah dikirim ke penerima, tidak dapat ditarik kembali.

⚠

Menghapus pesan yang merupakan satu-satunya pesan di utas juga akan menghapus utas tersebut.

Parameter Path

Parameter	Tipe	Deskripsi
`id` wajib	string (uuid)	ID pesan yang akan dihapus.

Contoh Request

javascript

await fetch(
  `https://api.agentsend.io/messages/${messageId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
); // 204 No Content

Respons — 204 No Content

Mengembalikan body kosong saat sukses.

Status Pengiriman

Field status berlanjut melalui status berikut untuk pesan keluar. Pesan masuk tiba dengan status: "received".

Status	Deskripsi
`queued`	Pesan diterima dan menunggu untuk dikirim.
`sending`	Sedang dikirim ke server email penerima.
`sent`	Diterima oleh server email penerima.
`delivered`	Pengiriman ke kotak surat penerima dikonfirmasi (jika didukung).
`failed`	Kegagalan pengiriman permanen. Periksa event webhook untuk detail.
`bounced`	Hard bounce — alamat tidak ada atau server menolak pengiriman.
`complained`	Penerima menandai pesan sebagai spam.
`received`	Pesan masuk yang diterima ke kotak masuk.

💡

Berlangganan webhooks untuk menerima transisi status real-time alih-alih polling endpoint GET.

← Sebelumnya API: Kotak Masuk Selanjutnya → API: Utas