Attachments

Upload files and attach them to outgoing emails. Incoming emails with attachments are automatically stored and accessible via the API.

Overview

AgentSend handles file attachments in both directions. For outgoing email, you upload a file first to get an attachment ID, then pass that ID when sending a message. For incoming email, any attachments the sender included are automatically stored and surfaced in the message object — no extra work required.

ℹ

Attachments are stored securely and served via short-lived presigned URLs. Download links expire after 1 hour — fetch a fresh URL from the API when you need to access a file.

Uploading an Attachment

Send a POST request to /attachments with the file as multipart/form-data. The response returns an attachment object with an id you can use when sending a message.

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"

Attachment Properties

Every attachment object contains the following fields:

Field	Type	Description
`id`	string	Unique attachment identifier (prefix `att_`).
`filename`	string	Original filename as uploaded or received.
`contentType`	string	MIME type, e.g. `application/pdf` or `image/png`.
`size`	number	File size in bytes.
`url`	string	Presigned download URL. Expires after 1 hour.
`createdAt`	string	ISO 8601 timestamp when the attachment was stored.

Attaching to Messages

Pass an attachmentIds array in the message body when sending. You can reference multiple attachments in a single message.

javascript

// 1. Upload the file
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. Send the message with the attachment
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],
  }),
});

Retrieving Attachments

Fetch a single attachment by ID with GET /attachments/{id}. The response includes a fresh presigned url you can use to download the file.

javascript

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

// Download the file using the presigned URL
const fileData = await fetch(attachment.url).then(r => r.arrayBuffer());

Incoming Attachments

When an inbound email arrives with attachments, AgentSend stores each file automatically. The message object will include an attachments array — each entry contains the metadata needed to identify and download the file.

json — inbound message (excerpt)

{
  "id": "msg_xyz",
  "subject": "Here's the contract",
  "attachments": [
    {
      "id": "att_a1b2c3",
      "filename": "contract.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ]
}

To download an incoming attachment, pass its id to GET /attachments/{id} to receive a presigned download URL as shown in the Retrieving Attachments section above.

Size Limits

The maximum size for a single attachment is 25 MB. This applies to both uploads and inbound attachments — files exceeding this limit on inbound email are discarded and a truncation note is added to the message.

⚠

Many receiving mail servers also enforce their own attachment size limits (often 10–25 MB). Keep attachments small or consider linking to files hosted externally for best deliverability.

← Zurück Domains Weiter Integrationen →