make.wordpress.org
## Metadata
- Author: [[make.wordpress.org]]
- Full Title: make.wordpress.org
- Category: #articles
- Document Tags: [[article]] [[processed]]
- Summary: make.wordpress.org
- URL: https://make.wordpress.org/core/2025/09/04/prettier-emails-supporting-inline-embedded-images/
An embedded email image is an image file included directly within the email’s content, allowing it to be displayed inline (i.e., in the body of an HTML email) without requiring the recipient to download it separately. This is achieved by referencing the image via a Content-ID (CID) in the email’s HTML markup. Embedded images are useful for enhancing visual emails, such as newsletters or branded notifications, but they only work in HTML-formatted emails. By default, WordPress sends emails in plain text format. To take advantage of embedded images, you must set the `Content-Type` header to `text/html` when calling `wp_mail()`.
Historically, the only way to add inline embedded images was to directly call `$phpmailer->AddEmbeddedImage` method during `phpmailer_init`, like this:
```
function embed_images( $phpmailer ) {
$phpmailer->AddEmbeddedImage( '/path/to/logo.png', 'logo.png' );
}
add_action( 'phpmailer_init', 'embed_images' );
```
This worked, but this specific implementation depended on the PHPMailer library.
The changes added in [#28059](https://core.trac.wordpress.org/ticket/28059)/[[60698]](https://core.trac.wordpress.org/changeset/60698) aim to provide a native option that facilitates some degree of abstraction from the current mailing library and also sets the stage to deprecate this native injection with `phpmailer_init` in the future, simplifying the process and ensuring long-term maintainability.
This change updates the `wp_mail` function signature to add a new argument for `$embeds`:
`wp_mail( $to, $subject, $message, $headers = '', $attachments = array(), $embeds = array())`
This new parameter can accept a newline-separated(`\n`) string of images paths, an array of image path strings, or an associative array of image paths where each key is the Content-ID.
#### Content-ID formation
When using the `$embeds` parameter to embed images for use in HTML emails, no changes are necessary for plain text emails. Reference the embedded file in your HTML code with a `cid:` URL whose value matches the file’s Content-ID.
**Example email markup:**
```
<img src="cid:0" alt="Logo">
<img src="cid:my-image" alt="Image">
```
As mentioned above, Content-ID (`cid`)s for each image path to be embedded can be passed using an associative array of `cid`/image path pairs. If `$embeds` is a newline-separated string or a non-associative array, the `cid` is a zero-based index of either the exploded string or the element’s position in the array.
#### New `wp_mail_embed_args` filter
A new `wp_mail_embed_args` filter has been introduced to allow each individual embed to be filtered during processing. With this new hook, it’s possible to customize most of the properties of each embed before passing to `$phpmailer->AddEmbeddedImage()`.
```
$embed_args = apply_filters(
'wp_mail_embed_args',
array(
'path' => $embed_path,
'cid' => $key,
'name' => basename( $embed_path ),
'encoding' => 'base64',
'type' => '',
'disposition' => 'inline',
)
);
```
Each of these values represents the following:
* *`path`* – The path to the image file
* *`cid`* – The `Content-ID`
* *`name`* – The filename of the image
* *`encoding`* – The encoding of the image
* *`type`* – The MIME `Content-Type`
* *`disposition`* – The disposition of the image
This provides a 1-to-1 representation of the PHPMailer’s `addEmbeddedImage` method via this hook.
**Example: Set the correct `Content-Type` when embedding SVG images:**
```
add_filter( 'wp_mail_embed_args', function ( $args ) {
if ( isset( $args['path'] ) && '.svg' === substr( $args['path'], -4 ) ) {
$args['type'] = 'image/svg+xml';
}
return $args;
} );
```
#### Backward Compatibility Recommendations
If you are maintaining code that completely replaces the `wp_mail()` function (e.g. via a custom implementation in a plugin or theme), take the following steps to improve the implementation with this update:
1. Update your implementation to expect and handle the new `$embeds` parameter in the function signature. This is optional, as `$embeds` receives an empty array by default.
2. Consider adding support for the `wp_mail_embed_args` filter to ensure that any plugins or themes making use of it will have their changes reflected in your implementation of `wp_mail()`.
3. If you are currently supporting images in your emails, they won’t be affected by this update. Although, adding this implementation will ensure greater integration with WordPress to safeguard against future deprecations.
As a reminder, fully replacing `wp_mail()` is generally discouraged. The `pre_wp_mail` filter introduced in WordPress 5.7 can accomplish the same result. For more details, see the [developer note on overriding wp\_mail() behavior](https://make.wordpress.org/core/2021/02/23/miscellaneous-developer-focused-changes-in-wordpress-5-7/#overriding-wp-mail-behavior)., make.wordpress.org, make.wordpress.org, 01k9w4xy8cepef7ymn5nvy464z.