Attachments | AgentMail | Documentation

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, include it in the attachments array when sending a Message. Each object in the array represents one file and must provide either content or url.

content: The Base64 encoded content of your file.
url: A URL that AgentMail can download without custom authentication headers or cookies. Redirects and pre-signed URLs are supported, and the final response must be a successful 2xx response.
filename (optional): The name of the file (e.g., invoice.pdf).
content_type (optional): The MIME type of the file (e.g., application/pdf).

Attachment size limits

Input	Limit	What counts toward the limit
Inline `content`	6 MB per request	The entire request, including the message body, metadata, and all attachments.
Remote `url`	Around 30 MB of attachments per message	The combined size of the files AgentMail downloads from all attachment URLs.

If an inline request exceeds 6 MB, the API returns 413 Request Entity Too Large. For larger files, use URL-backed attachments and keep the combined attachment size around 30 MB per message.

To detect the inline limit proactively, measure the complete serialized request and leave room for the message body and metadata. Use url for larger attachments.

1 import base64
2 
3 # A simple text file for this example
4 
5 file_content = "This is the content of our report."
6 
7 # You must Base64 encode the file content before sending
8 
9 encoded_content = base64.b64encode(file_content.encode()).decode()
10 
11 sent_message = client.inboxes.messages.send(
12 inbox_id="reports@agentmail.to",
13 to=["supervisor@example.com"],
14 subject="Q4 Financial Report",
15 text="Please see the attached report.",
16 attachments=[{
17 "content": encoded_content,
18 "filename": "Q4-report.txt",
19 "content_type": "text/plain"
20 }]
21 )

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.

1 inbox_id = "inbox_123"
2 message_id = "<def456@agentmail.to>"
3 attachment_id = "attach_789" # From the message object
4 
5 file_data = client.inboxes.messages.get_attachment(
6 inbox_id=inbox_id,
7 message_id=message_id,
8 attachment_id=attachment_id
9 )
10 
11 # Now you can save the file
12 
13 with open("downloaded_file.pdf", "wb") as f:
14 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.

1 inbox_id = "inbox_123"
2 thread_id = "thread_abc"
3 attachment_id = "attach_789" # From a message within the thread
4 
5 file_data = client.inboxes.threads.get_attachment(
6 inbox_id=inbox_id,
7 thread_id=thread_id,
8 attachment_id=attachment_id
9 )

Copy for Cursor / Claude

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

1 """
2 AgentMail Attachments — copy into Cursor/Claude.
3 
4 Send: attachments=[{ content: base64_string, filename?, content_type? }] in messages.send/reply.
5 Get attachment_id from message.attachments or thread.attachments.
6 
7 - messages.get_attachment(inbox_id, message_id, attachment_id) → bytes
8 - threads.get_attachment(inbox_id, thread_id, attachment_id) → bytes
9 """
10 import base64
11 from agentmail import AgentMail
12 
13 client = AgentMail(api_key="YOUR_API_KEY")
14 
15 encoded = base64.b64encode(b"file content").decode()
16 client.inboxes.messages.send(
17   "agent@agentmail.to",
18   to="user@example.com",
19   subject="Report",
20   text="See attachment",
21   attachments=[{"content": encoded, "filename": "report.txt", "content_type": "text/plain"}],
22 )
23 
24 data = client.inboxes.messages.get_attachment("inbox@am.to", "<abc123@agentmail.to>", "att_456")
25 with open("downloaded.pdf", "wb") as f:
26   f.write(data)

What are Attachments?

Sending Attachments