Email Attachments & Tags
Relevant source files
The following files were used as context for generating this wiki page:
Email Attachments and Tags provide metadata and file handling capabilities for outgoing and incoming messages. Attachments allow you to send local or remote files with your emails, while Tags enable categorization and tracking of messages for better reporting and webhook processing.
These components are integrated into the Emails.send workflow and are also accessible when retrieving received emails or managing inbox drafts.
Sources: resend/emails/_emails.py:165-172, examples/with_attachments.py:18-30
Email Attachments
Attachments in Resend are handled through several specialized classes depending on the context of the email (outbound vs. inbound) and the source of the file (local bytes vs. remote URL).
Outbound Attachment Types
For sending emails, the SDK supports two primary attachment structures:
- Standard Attachment: Used for sending local files. It requires a filename and the file content.
- Remote Attachment: Used for sending files hosted on a remote server via a URL.
Sources: resend/emails/_attachment.py:7-35, resend/emails/_emails.py:149-152
| Field | Type | Description |
|---|---|---|
content | Union[List[int], str, bytes] | The file content (local attachments). |
filename | str | Name of the file as it appears to the recipient. |
path | str | URL of the remote file (remote attachments). |
content_type | NotRequired[str] | The MIME type of the file. |
content_id | NotRequired[str] | Used for inline images (e.g., cid:image_id). |
Sources: resend/emails/_attachment.py:7-35, resend/emails/_emails.py:165-172
Inbox Draft Attachments
When creating or updating drafts in an Inbox, the system uses a specific AttachmentParams structure. Draft attachments must be provided as base64-encoded strings and are subject to a total size limit of 25 MB.
Sources: resend/inboxes/drafts/_inbox_drafts.py:27-44, resend/inboxes/drafts/_inbox_drafts.py:108-118
Attachment Data Flow
The following diagram illustrates how an attachment moves from a local file or remote URL through the Resend API.
A flowchart showing the progression of attachment data from the client application to the Resend API storage.
Sources: resend/emails/_emails.py:236-254, examples/with_attachments.py:18-30
Email Tags
Tags are key-value pairs assigned to emails to facilitate filtering and tracking. They are particularly useful for identifying specific campaigns or users in webhook payloads.
Tag Structure
A tag consists of a required name and an optional value.
Sources: resend/emails/_tag.py:4-15
| Attribute | Type | Description |
|---|---|---|
name | str | The key or identifier for the tag. |
value | NotRequired[str] | The value associated with the tag key. |
Sources: resend/emails/_tag.py:7-15
Implementation Example
tag: resend.Tag = {
"name": "category",
"value": "onboarding"
}
params: resend.Emails.SendParams = {
"from": "onboarding@resend.dev",
"to": ["user@example.com"],
"subject": "Welcome",
"tags": [tag]
}
Sources: resend/emails/_emails.py:171-172, resend/emails/_tag.py:4-15
Inbound Attachments
When receiving emails via webhooks or the Receiving API, attachment data is returned as metadata. The actual binary content is not included in the initial response; instead, a download_url is provided through a separate retrieval call.
Received Email Attachment Metadata
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the attachment. |
filename | Optional[str] | The original filename. |
content_type | str | MIME type (e.g., application/pdf). |
size | Optional[int] | Size of the file in bytes. |
Sources: resend/webhooks/_webhook_event.py:80-101, resend/webhooks/_webhook_event.py:321-332
Attachment Retrieval Sequence
The sequence below describes how a developer retrieves the actual file content for a received email.
A sequence diagram showing the two-step process to retrieve attachment metadata and then the secure download URL.
Sources: resend/emails/_attachments.py:76-92, resend/emails/_attachments.py:108-124
Attachment and Tag Limits
The system enforces specific constraints on attachments and tags to ensure performance and reliability.
- Recipients & Body: Creating or updating drafts with attachments must ensure that at least one field (to, cc, bcc, subject, text, html, or attachments) is non-empty.
- Draft Size: Files stored on a draft cannot exceed a total of 25 MB.
- Draft Attachments: Sending
attachments: []orNonein an update request removes all existing attachments from the draft. - Webhook Tags: Tags associated with an email are included in the
BaseEmailEventDataof outbound webhook events.
Sources: resend/inboxes/drafts/_inbox_drafts.py:65-71, resend/inboxes/drafts/_inbox_drafts.py:126-135, resend/webhooks/_webhook_event.py:130-133
Conclusion
The Email Attachments and Tags system provides a robust framework for handling file data and message metadata. By utilizing local, remote, or draft-based attachments, users can deliver complex content, while tags ensure that these messages remain traceable and organized throughout their lifecycle from delivery to webhook notification.