## 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](/content/docs/email-deliverability/index.html)). 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`).

```python
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.

```python
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.

```python
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.

```python
"""
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)
```