Email attachments in SES are files that you can include with your email messages
when using the SES API v2 SendEmail and SendBulkEmail
operations. This feature enables you to enrich your email content by including documents
such as PDFs, Word files, images, or other file types that comply with SES supported
MIME types. You can also include inline images that render directly in the email content
without requiring recipients to download them separately. You can include multiple
attachments per email, up to the 40MB total message size limit.
Note
SendEmail
SES API v2 with Raw content type, SMTP interface, and SES API v1
continue to handle attachments through raw email
MIME message construction.
How attachments work in SES
There are two different types of encoding that happen at different stages when sending an email with attachments:
Stage 1 – Sending data to SES:
-
When you want to send an attachment to SES, the binary data (like a PDF or image) needs to be converted into a format that can be transmitted safely.
-
This is where base64-encoding comes in—it's required because you can't send raw binary data in a JSON request.
-
If you're using the AWS SDK, it handles this encoding automatically.
-
If you're using the AWS CLI, you need to base64-encode the attachment yourself before sending it.
Stage 2 – SES creating the email:
-
Once SES receives your data, it needs to create an actual email with the attachment.
-
This is where the ContentTransferEncoding setting comes into play.
-
SES will use whatever encoding method you specify in ContentTransferEncoding to automatically format the attachment in the final email.
Think of it like this—it's similar to sending a package through the mail. First, you need to get the package to the post office (Stage 1 - Base64-encoding required), then the post office will package it appropriately for final delivery (Stage 2 - ContentTransferEncoding).
Attachment object structure
When you send an email with attachments through SES, the service handles the
complex MIME message construction automatically. You simply need to provide the
attachment content and metadata through the following the SES API v2 Attachment object
structure:
-
FileName(Required) – The file name displayed to recipients (must include file extension). If not provided, SES will derive aContentTypefrom the extension of theFileName. -
ContentType(Optional) – IANA-compliant media type identifier. -
ContentDisposition(Optional) – Specifies how the attachment should be rendered:ATTACHMENT(default) orINLINE. -
ContentDescription(Optional) – Short description of the content. -
RawContent(Required) – The actual content of the attachment. -
ContentTransferEncoding(Optional) – Specifies the encoding type of the content:SEVEN_BIT(default),BASE64orQUOTED_PRINTABLE.
All attached content must be encoded to base64, such as:
-
Plain text content:
Text attachment sample content. -
Base64 encoded:
VGV4dCBhdHRhY2htZW50IHNhbXBsZSBjb250ZW50Lg==
The following examples show how to use the attachment object structure when specifying
attachments with the SES API v2 SendEmail and SendBulkEmail
operations using the AWS CLI referencing a JSON file containing attachment object
elements.
Example – SendEmail with simple content
aws sesv2 send-email --cli-input-json file://request-send-email-simple.jsonrequest-send-email-simple.json
{
"FromEmailAddress": "sender@example.com",
"Destination": {
"ToAddresses": [
"recipient@example.com"
]
},
"Content": {
"Simple": {
"Subject": {
"Data": "Email with attachment"
},
"Body": {
"Text": {
"Data": "Please see attached document."
},
"Html": {
"Data": "Please see attached <b>document</b>."
}
},
"Attachments": [
{
"RawContent": "<base64-encoded-content>",
"ContentDisposition": "ATTACHMENT",
"FileName": "document.pdf",
"ContentDescription": "PDF Document Attachment",
"ContentTransferEncoding": "BASE64"
}
]
}
}
}Example – SendEmail with simple content and inline attachment
aws sesv2 send-email --cli-input-json file://request-send-email-simple-inline-attachment.jsonrequest-send-email-simple-inline-attachment.json
{
"FromEmailAddress": "sender@example.com",
"Destination": {
"ToAddresses": [
"recipient@example.com"
]
},
"Content": {
"Simple": {
"Subject": {
"Data": "Email with attachment"
},
"Body": {
"Html": {
"Data": "<html><body>Our logo:<br><img src=\"cid:logo123\" alt=\"Company Logo\"></body></html>"
}
},
"Attachments": [
{
"RawContent": "<base64-encoded-content>",
"ContentDisposition": "INLINE",
"FileName": "logo.png",
"ContentId": "logo123"
}
]
}
}
}Example – SendEmail with template content
aws sesv2 send-email --cli-input-json file://request-send-email-template.jsonrequest-send-email-template.json
{
"FromEmailAddress": "sender@example.com",
"Destination": {
"ToAddresses": [
"recipient@example.com"
]
},
"Content": {
"Template": {
"TemplateName": "MyTemplate",
"TemplateData": "{\"name\":\"John\"}",
"Attachments": [
{
"RawContent": "<base64-encoded-content>",
"ContentDisposition": "ATTACHMENT",
"FileName": "document.pdf",
"ContentDescription": "PDF Document Attachment",
"ContentTransferEncoding": "BASE64"
}
]
}
}
}Example – SendBulkEmail with attachment content
aws sesv2 send-bulk-email --cli-input-json file://request-send-bulk-email.jsonrequest-send-bulk-email.json
{
"FromEmailAddress": "sender@example.com",
"DefaultContent": {
"Template": {
"TemplateName": "MyTemplate",
"TemplateData": "{}",
"Attachments": [
{
"RawContent": "<base64-encoded-content>",
"ContentDisposition": "ATTACHMENT",
"FileName": "document.pdf",
"ContentDescription": "PDF Document Attachment",
"ContentTransferEncoding": "BASE64"
}
]
}
},
"BulkEmailEntries": [
{
"Destination": {
"ToAddresses": [
"recipient@example.com"
]
},
"ReplacementEmailContent": {
"ReplacementTemplate": {
"ReplacementTemplateData": "{\"name\":\"John\"}"
}
}
}
]
}Best practices
-
Keep total message size (including attachments) under 40MB.
-
Let SES auto-detect content types based on file extensions when possible.
-
Explicitly specify content types only when they fall outside of the common MIME types
. -
Consider using inline images for better email rendering.
-
SES supports a wide range of MIME types for attachments, except for those listed in Unsupported attachment types.
SES unsupported attachment types
You can send messages with attachments through Amazon SES by using the Multipurpose Internet Mail Extensions (MIME) standard. Amazon SES accepts all file attachment types except for attachments with the file extensions in the following list.
.ade .adp .app .asp .bas .bat .cer .chm .cmd .com .cpl .crt .csh .der .exe .fxp .gadget .hlp |
.hta .inf .ins .isp .its .js .jse .ksh .lib .lnk .mad .maf .mag .mam .maq .mar .mas .mat |
.mau .mav .maw .mda .mdb .mde .mdt .mdw .mdz .msc .msh .msh1 .msh2 .mshxml .msh1xml .msh2xml .msi .msp |
.mst .ops .pcd .pif .plg .prf .prg .reg .scf .scr .sct .shb .shs .sys .ps1 .ps1xml .ps2 .ps2xml |
.psc1 .psc2 .tmp .url .vb .vbe .vbs .vps .vsmacros .vss .vst .vsw .vxd .ws .wsc .wsf .wsh .xnk |
Some ISPs have further restrictions (such as restrictions regarding archived attachments), so we recommend testing your email sending through major ISPs before you send your production email.
