Tin Nhắn

Tin nhắn đại diện cho từng email được gửi hoặc nhận bởi một hộp thư. Gửi email HTML phong phú, theo dõi trạng thái giao, và đọc phản hồi đến.

Tổng Quan

Một tin nhắn là một email duy nhất gắn với một hộp thư. Khi agent của bạn gửi một email, nó tạo ra một tin nhắn gửi đi. Khi có người trả lời hoặc gửi email đến địa chỉ của agent, một tin nhắn đến sẽ được tạo tự động.

Mỗi tin nhắn thuộc về một chuỗi hội thoại — có thể là chuỗi đã tồn tại (cho các phản hồi) hoặc một chuỗi mới được tạo tự động khi bắt đầu cuộc hội thoại mới.

Gửi Email

POST /inboxes/{inboxId}/messages

Gửi email từ một hộp thư bằng cách post tới endpoint messages của nó. Mảng to và subject là bắt buộc; mọi thứ khác là tùy chọn.

Nội Dung Yêu Cầu

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"],
      subject: "Following up on your request",
      bodyText: "Hi, just checking in on your request.",
      bodyHtml: "<p>Hi, just checking in on your request.</p>",
    }),
  }
);

const message = await res.json();
console.log(message.id);     // msg_abc123
console.log(message.delivery); // "email" or "dry-run"
console.log(message.status); // "queued"

Thuộc Tính Tin Nhắn

Mỗi đối tượng tin nhắn được API trả về có các trường sau.

Trạng Thái Tin Nhắn

Tin nhắn gửi đi đi qua một vòng đời giao hàng. Kiểm tra delivery trước để xác nhận môi trường đã gửi email thật hay chỉ mô phỏng, sau đó dùng status hoặc webhooks để theo dõi vòng đời phía nhà cung cấp.

Vòng đời gửi đi

• queued — Tin nhắn đã được chấp nhận và đang đợi được gửi.
• sending — Tin nhắn đang được giao đến máy chủ email của người nhận.
• sent — Tin nhắn đã được máy chủ email của người nhận chấp nhận.
• delivered — Xác nhận giao thành công (nếu máy chủ nhận hỗ trợ).

Trạng thái thất bại

• failed — Lỗi tạm thời hoặc vĩnh viễn ngăn việc giao. Kiểm tra payload webhook để biết lý do.
• bounced — Địa chỉ người nhận không tồn tại hoặc máy chủ từ chối vĩnh viễn.
• complained — Người nhận đánh dấu email là spam.

Tin nhắn đến

• received — Một email đã đến hộp thư từ người gửi bên ngoài.

Liệt Kê Tin Nhắn

GET /inboxes/{inboxId}/messages

Lấy danh sách có phân trang các tin nhắn của một hộp thư. Lọc theo trạng thái để tìm tin nhắn đến, gửi thất bại, hoặc bất kỳ tập con nào khác.

// Lấy 10 tin nhắn đến gần nhất
const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=10`,
  { 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, msg.bodyText);
}

HTML và Văn Bản Thuần

AgentSend hỗ trợ email văn bản thuần, HTML, và multipart. Sử dụng bodyText cho văn bản thuần và bodyHtml cho nội dung HTML.

• Nếu bạn chỉ cung cấp bodyText, email được gửi dưới dạng text/plain.
• Nếu bạn chỉ cung cấp bodyHtml, email được gửi dưới dạng text/html.
• Nếu bạn cung cấp cả hai, email được gửi dưới dạng multipart/alternative. Email client hỗ trợ HTML sẽ hiển thị phiên bản HTML; các client khác sẽ hiển thị phiên bản văn bản thuần.

Xóa Tin Nhắn

DELETE /messages/{id}

Xóa một tin nhắn theo ID. Điều này xóa bản ghi tin nhắn khỏi AgentSend. Nó không thu hồi một email đã được giao khỏi hộp thư người nhận.

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