Tệp Đính Kèm

Tải tệp lên và đính kèm vào email gửi đi. Email đến có tệp đính kèm được tự động lưu trữ và truy cập được qua API.

Tổng Quan

AgentSend xử lý tệp đính kèm theo cả hai hướng. Với email gửi đi, trước tiên bạn tải tệp lên để lấy ID tệp đính kèm, sau đó truyền ID đó khi gửi tin nhắn. Với email đến, mọi tệp đính kèm người gửi bao gồm sẽ được lưu trữ tự động và xuất hiện trong đối tượng tin nhắn — không cần làm thêm.

Tệp đính kèm được lưu trữ an toàn và phục vụ qua URL presigned có thời hạn ngắn. Liên kết tải xuống hết hạn sau 1 giờ — lấy URL mới từ API khi bạn cần truy cập tệp.

Tải Lên Tệp Đính Kèm

Gửi yêu cầu POST đến /attachments với tệp dạng multipart/form-data. Phản hồi trả về một đối tượng tệp đính kèm với id bạn có thể dùng khi gửi tin nhắn.

curl
curl -X POST https://api.agentsend.io/attachments \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -F "file=@/path/to/report.pdf"
javascript
const form = new FormData();
form.append("file", fileBlob, "report.pdf");

const res = await fetch("https://api.agentsend.io/attachments", {
  method: "POST",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  body: form,
});

const attachment = await res.json();
console.log(attachment.id); // e.g. "att_a1b2c3d4"

Thuộc Tính Tệp Đính Kèm

Mỗi đối tượng tệp đính kèm chứa các trường sau:

Trường Kiểu Mô tả
id string Định danh duy nhất của tệp đính kèm (tiền tố att_).
filename string Tên tệp gốc khi tải lên hoặc nhận được.
contentType string Loại MIME, ví dụ application/pdf hoặc image/png.
size number Kích thước tệp tính bằng byte.
url string URL tải xuống presigned. Hết hạn sau 1 giờ.
createdAt string Dấu thời gian ISO 8601 khi tệp đính kèm được lưu trữ.

Đính Kèm Vào Tin Nhắn

Truyền mảng attachmentIds vào body tin nhắn khi gửi. Bạn có thể tham chiếu nhiều tệp đính kèm trong một tin nhắn.

javascript
// 1. Tải tệp lên
const form = new FormData();
form.append("file", fileBlob, "invoice.pdf");
const { id: attachmentId } = await fetch("https://api.agentsend.io/attachments", {
  method: "POST",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  body: form,
}).then(r => r.json());

// 2. Gửi tin nhắn với tệp đính kèm
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: "Your invoice",
    bodyText: "Please find your invoice attached.",
    attachmentIds: [attachmentId],
  }),
});

Lấy Tệp Đính Kèm

Lấy một tệp đính kèm theo ID với GET /attachments/{id}. Phản hồi bao gồm một url presigned mới mà bạn có thể dùng để tải xuống tệp.

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

// Tải tệp xuống bằng URL presigned
const fileData = await fetch(attachment.url).then(r => r.arrayBuffer());

Tệp Đính Kèm Đến

Khi email đến có tệp đính kèm, AgentSend tự động lưu trữ từng tệp. Đối tượng tin nhắn sẽ bao gồm mảng attachments — mỗi mục chứa metadata cần thiết để nhận dạng và tải xuống tệp.

json — tin nhắn đến (trích)
{
  "id": "msg_xyz",
  "subject": "Here's the contract",
  "attachments": [
    {
      "id": "att_a1b2c3",
      "filename": "contract.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ]
}

Để tải tệp đính kèm đến, truyền id của nó vào GET /attachments/{id} để nhận URL tải xuống presigned như được hiển thị trong phần Lấy Tệp Đính Kèm ở trên.

Giới Hạn Kích Thước

Kích thước tối đa cho một tệp đính kèm là 25 MB. Điều này áp dụng cho cả tải lên và tệp đính kèm đến — các tệp vượt quá giới hạn này trên email đến sẽ bị loại bỏ và một ghi chú cắt bớt được thêm vào tin nhắn.

Nhiều máy chủ email nhận cũng thực thi giới hạn kích thước tệp đính kèm riêng (thường 10–25 MB). Giữ tệp đính kèm nhỏ hoặc xem xét liên kết đến tệp được lưu trữ ở ngoài để có khả năng giao tốt nhất.