Attachments

Fresh 🌱

Learn how to send files as attachments, and download incoming attachments from both messages and threads.

What are Attachments?

An Attachment is a file that is associated with a Message. This can be anything from a PDF invoice to a CSV report or an image(though we don't recommend sending images in the first email sent. We go more into this in the deliverability section). Your agents can both send Attachments in outgoing Messages and process Attachments from incoming Messages.

Sending Attachments

To send a file, you include it in an Attachments array when sending a Message. Each object in the array represents one file and must have a content property.

• content (required): The Base64 encoded content of your file.
• filename (optional): The name of the file (e.g., invoice.pdf).
• content_type (optional): The MIME type of the file (e.g., application/pdf).

import base64

# A simple text file for this example

file_content = "This is the content of our report."

# You must Base64 encode the file content before sending

encoded_content = base64.b64encode(file_content.encode()).decode()

sent_message = client.inboxes.messages.send(
inbox_id="reports@agentmail.to",
to=["supervisor@example.com"],
subject="Q4 Financial Report",
text="Please see the attached report.",
attachments=[{
"content": encoded_content,
"filename": "Q4-report.txt",
"content_type": "text/plain"
}]
)

// A simple text file for this example
const fileContent = "This is the content of our report.";
// You must Base64 encode the file content before sending
const encodedContent = Buffer.from(fileContent).toString("base64");

const sentMessage = await client.inboxes.messages.send("reports@agentmail.to", {
  to: ["supervisor@example.com"],
  subject: "Q4 Financial Report",
  text: "Please see the attached report.",
  attachments: [{
    content: encodedContent,
    filename: "Q4-report.txt",
    contentType: "text/plain",
  }],
});

# send a message with a base64-encoded attachment
agentmail inboxes:messages send \
  --inbox-id reports@agentmail.to \
  --to supervisor@example.com \
  --subject "Q4 Financial Report" \
  --text "Please see the attached report." \
  --attachment.content "VGhpcyBpcyB0aGUgY29udGVudCBvZiBvdXIgcmVwb3J0Lg==" \
  --attachment.filename "Q4-report.txt" \
  --attachment.content-type "text/plain"

Retrieving Attachments

To retrieve an Attachment, you first need its attachment_id. You can get this ID from the attachments array on a Message object. Once you have the ID, you can download the file.

The API response for getting an attachment is the raw file itself, which you can then save to disk or process in memory.

From a Specific Message

If you know the Message an Attachment belongs to, you can retrieve it directly.

inbox_id = "inbox_123"
message_id = "<def456@agentmail.to>"
attachment_id = "attach_789" # From the message object

file_data = client.inboxes.messages.get_attachment(
inbox_id=inbox_id,
message_id=message_id,
attachment_id=attachment_id
)

# Now you can save the file

with open("downloaded_file.pdf", "wb") as f:
f.write(file_data)

const inboxId = "inbox_123";
const messageId = "<def456@agentmail.to>";
const attachmentId = "attach_789"; // From the message object

const fileData = await client.inboxes.messages.get_attachment(
  inboxId,
  messageId,
  attachmentId
);

// fileData is a Blob/Buffer that you can process
// For example, in Node.js:
// import fs from 'fs';
// fs.writeFileSync('downloaded_file.pdf', fileData);

# get an attachment from a specific message
agentmail inboxes:messages get-attachment \
  --inbox-id inbox_123 \
  --message-id "<def456@agentmail.to>" \
  --attachment-id attach_789

From a Specific Thread

Similarly, you can retrieve an Attachment if you know the Thread it's in, which can be more convenient for multi-message conversations.

inbox_id = "inbox_123"
thread_id = "thread_abc"
attachment_id = "attach_789" # From a message within the thread

file_data = client.inboxes.threads.get_attachment(
inbox_id=inbox_id,
thread_id=thread_id,
attachment_id=attachment_id
)

const inboxId = "inbox_123";
const threadId = "thread_abc";
const attachmentId = "attach_789"; // From a message within the thread

const fileData = await client.inboxes.threads.get_attachment(
  inboxId,
  threadId,
  attachmentId
);

# get an attachment from a specific thread
agentmail inboxes:threads get-attachment \
  --inbox-id inbox_123 \
  --thread-id thread_abc \
  --attachment-id attach_789

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for complete Attachments usage in one shot.

"""
AgentMail Attachments — copy into Cursor/Claude.

Send: attachments=[{ content: base64_string, filename?, content_type? }] in messages.send/reply.
Get attachment_id from message.attachments or thread.attachments.

- messages.get_attachment(inbox_id, message_id, attachment_id) → bytes
- threads.get_attachment(inbox_id, thread_id, attachment_id) → bytes
"""
import base64
from agentmail import AgentMail

client = AgentMail(api_key="YOUR_API_KEY")

encoded = base64.b64encode(b"file content").decode()
client.inboxes.messages.send(
  "agent@agentmail.to",
  to="user@example.com",
  subject="Report",
  text="See attachment",
  attachments=[{"content": encoded, "filename": "report.txt", "content_type": "text/plain"}],
)

data = client.inboxes.messages.get_attachment("inbox@am.to", "<abc123@agentmail.to>", "att_456")
with open("downloaded.pdf", "wb") as f:
  f.write(data)

/**
 * AgentMail Attachments — copy into Cursor/Claude.
 *
 * Send: attachments: [{ content: base64String, filename?, contentType? }] in messages.send/reply.
 * Get attachmentId from message.attachments or thread.attachments.
 *
 * - messages.get_attachment(inboxId, messageId, attachmentId) → Buffer/Blob
 * - threads.get_attachment(inboxId, threadId, attachmentId) → Buffer/Blob
 */
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const encoded = Buffer.from("file content").toString("base64");
await client.inboxes.messages.send("agent@agentmail.to", {
  to: "user@example.com",
  subject: "Report",
  text: "See attachment",
  attachments: [{ content: encoded, filename: "report.txt", contentType: "text/plain" }],
});

const data = await client.inboxes.messages.get_attachment("inbox@am.to", "<abc123@agentmail.to>", "att_456");