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"
    }]
)

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.

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)

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
)

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)