wp_mail( string|string[] $to, string $subject, string $message, string|string[] $headers = '', string|string[] $attachments = array(), string|string[] $embeds = array() ): bool
- Since
- 1.2.1, 5.5.0, 6.9.0, 6.9.0
- Source
wp-includes/pluggable.php:189
Description
A true return value does not automatically mean that the user received the email successfully. It just only means that the method used was able to process the request without any errors.
The default content type is text/plain which does not allow using HTML.
However, you can set the content type of the email by using the 'wp_mail_content_type' filter.
The default charset is based on the charset used on the blog. The charset can be set using the 'wp_mail_charset' filter.
When using the $embeds parameter to embed images for use in HTML emails, reference the embedded file in your HTML with a cid: URL whose value matches the file's Content-ID. By default, the Content-ID (cid) used for each embedded file is the key in the embeds array, unless modified via the 'wp_mail_embed_args' filter. For example:
<img src="cid:0" alt="Logo"> <img src="cid:my-image" alt="Image">
You may also customize the Content-ID for each file by using the 'wp_mail_embed_args' filter and setting the cid value.
Compatibility
- WordPress
- since 6.9.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$tostring|string[]- Array or comma-separated list of email addresses to send message.
$subjectstring- Email subject.
$messagestring- Message contents.
$headersstring|string[]optional- Additional headers.Default:
'' $attachmentsstring|string[]optional- Paths to files to attach.Default:
array() $embedsstring|string[]optional- Paths to files to embed.Default:
array()
Return value
bool- Whether the email was sent successfully.
Performance profile
How much work a call to wp_mail() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Expensive
- Scaling
- Constant
- Instructions
- 6
- Plugin surface
- 10 hooks
- Called by
- 28
Sends mail.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5. The body compiles to 610.
Third-party callbacks on 'wp_mail', 'pre_wp_mail', 'wp_mail_from' run inside this call, and their cost is not bounded by anything here.
28 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- mailsends mail
wp_mail()this function does it - hookthird-party callbacks
apply_filters()called directly - optionoption read or write
get_option()one call below wp_mail()
Further down the call graph this can also reach cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 1 distinct outcome
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_mail() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 6 | is_email() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 610 | 6 | 62 | |
| 8.5 | 610 | 6 | 62 | |
| 8.4 | 610 | 6 | 62 | 77 fewer instructions than PHP 8.3 |
| 8.3 | 687 | 6 | 62 | |
| 8.2 | 687 | 6 | 62 | 2 more instructions than PHP 8.1 |
| 8.1 | 685 | 6 | 62 | 1 more instruction than PHP 7.4 |
| 7.4 | 684 | 6 | 62 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 11
11 hooks fire while wp_mail() runs, in this order:
- apply_filters( pre_wp_mail )filterline 233 (+44 into the body)
Filters whether to preempt sending an email.
- apply_filters( wp_mail_from )filterline 437 (+248 into the body)
Filters the email address to send from.
- apply_filters( wp_mail_from_name )filterline 446 (+257 into the body)
Filters the name to associate with the "from" email address.
- do_action( wp_mail_failed )actionline 455 (+266 into the body)
Fires after a PHPMailer exception is caught.
- apply_filters( wp_mail_content_type )filterline 521 (+332 into the body)
Filters the wp_mail() content type.
- apply_filters( wp_mail_charset )filterline 542 (+353 into the body)
Filters the default wp_mail() charset.
- apply_filters( wp_mail_embed_args )filterline 588 (+399 into the body)
Filters the arguments for PHPMailer's addEmbeddedImage() method.
- do_action( wp_mail_succeeded )actionline 651 (+462 into the body)
Fires after PHPMailer has successfully sent an email.
- do_action( wp_mail_failed )actionline 665 (+476 into the body)
Fires after a PHPMailer exception is caught.
Uses · 12
- apply_filters()Calls the callback functions that have been added to a filter hook.
- is_email()Verifies that an email is valid.
- str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
- stripos()
- wp_parse_url()A wrapper for PHP's parse_url() function that handles consistency in the return values across PHP versions.
- network_home_url()Retrieves the home URL for the current network.
- str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
- do_action()Calls the callback functions that have been added to an action hook.
- get_bloginfo()Retrieves information about the current site.
- do_action_ref_array()Calls the callback functions that have been added to an action hook, specifying arguments in an array.
- WP_PHPMailer::__construct()Constructor.
- WP_Error::__construct()Initializes the error.
Used by · 28
- WP_Automatic_Updater::send_debug_email()Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
- WP_Automatic_Updater::send_email()Sends an email upon the completion or failure of a background core update.
- WP_Automatic_Updater::send_plugin_theme_email()Sends an email upon the completion or failure of a plugin or theme background update.
- WP_Recovery_Mode_Email_Service::send_recovery_mode_email()Sends the Recovery Mode email to the site admin email address.
- _wp_privacy_send_erasure_fulfillment_notification()Notifies the user when their erasure request is fulfilled.
- _wp_privacy_send_request_confirmation_notification()Notifies the site administrator via email when a request is confirmed.
- newblog_notify_siteadmin()Notifies the network admin that a new site has been activated.
- newuser_notify_siteadmin()Notifies the network admin that a new user has been activated.
- retrieve_password()Handles sending a password retrieval email to a user.
- send_confirmation_on_profile_email()Sends a confirmation request email when a change of user email address is attempted.
- update_network_option_new_admin_email()Sends a confirmation request email when a change of network admin email address is attempted.
- update_option_new_admin_email()Sends a confirmation request email when a change of site admin email address is attempted.
Show all 28
- wp_network_admin_email_change_notification()Sends an email to the old network admin email address when the network admin email address changes.
- wp_new_blog_notification()Notifies the site admin that the installation of WordPress is complete.
- wp_new_user_notification()Emails login credentials to a newly-registered user.
- wp_notify_moderator()Notifies the moderator of the site about a new comment that is awaiting approval.
- wp_notify_postauthor()Notifies an author (and/or others) of a comment/trackback/pingback on a post.
- wp_password_change_notification()Notifies the blog admin of a user changing password, normally via email.
- wp_privacy_send_personal_data_export_email()Send an email to the user with a link to the personal data export file
- wp_send_note_notification()Sends a single note mention notification email.
- wp_send_user_request()Send a confirmation request email to confirm an action.
- wp_site_admin_email_change_notification()Sends an email to the old site admin email address when the site admin email address changes.
- wp_update_user()Updates a user in the database.
- wpmu_new_site_admin_notification()Notifies the Multisite network administrator that a new site was created.
- wpmu_signup_blog_notification()Sends a confirmation request email to a user when they sign up for a new site. The new site will not become active until the confirmation link is clicked.
- wpmu_signup_user_notification()Sends a confirmation request email to a user when they sign up for a new user account (without signing up for a site at the same time). The user account will not become active until the confirmation link is clicked.
- wpmu_welcome_notification()Notifies the site administrator that their site activation was successful.
- wpmu_welcome_user_notification()Notifies a user that their account activation has been successful.
Source code
function wp_mail( $to, $subject, $message, $headers = '', $attachments = array(), $embeds = array() ) { // Compact the input, apply the filters, and extract them back out. /** * Filters the wp_mail() arguments. * * @since 2.2.0 * @since 6.9.0 The `$embeds` element was added to the `$args` array. * * @param array $args { * Array of the `wp_mail()` arguments. * * @type string|string[] $to Array or comma-separated list of email addresses to send message. * @type string $subject Email subject. * @type string $message Message contents. * @type string|string[] $headers Additional headers. * @type string|string[] $attachments Paths to files to attach. * @type string|string[] $embeds Paths to files to embed. * } */ $atts = apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers', 'attachments', 'embeds' ) ); /** * Filters whether to preempt sending an email. * * Returning a non-null value will short-circuit {@see wp_mail()}, returning * that value instead. A boolean return value should be used to indicate whether * the email was successfully sent. * * @since 5.7.0 * @since 6.9.0 The `$embeds` element was added to the `$atts` array. * * @param null|bool $return Short-circuit return value. * @param array $atts { * Array of the `wp_mail()` arguments. * * @type string|string[] $to Array or comma-separated list of email addresses to send message. * @type string $subject Email subject. * @type string $message Message contents. * @type string|string[] $headers Additional headers. * @type string|string[] $attachments Paths to files to attach. * @type string|string[] $embeds Paths to files to embed. * } */ $pre_wp_mail = apply_filters( 'pre_wp_mail', null, $atts ); if ( null !== $pre_wp_mail ) { return $pre_wp_mail; } if ( isset( $atts['to'] ) ) { $to = $atts['to']; } if ( ! is_array( $to ) ) { $to = explode( ',', $to ); } if ( isset( $atts['subject'] ) ) { $subject = $atts['subject']; } if ( isset( $atts['message'] ) ) { $message = $atts['message']; } if ( isset( $atts['headers'] ) ) { $headers = $atts['headers']; } if ( isset( $atts['attachments'] ) ) { $attachments = $atts['attachments']; } if ( ! is_array( $attachments ) ) { $attachments = explode( "\n", str_replace( "\r\n", "\n", $attachments ) ); } if ( isset( $atts['embeds'] ) ) { $embeds = $atts['embeds'];Changelog
Introduced in 1.2.1. One change between 6.7.7 and 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
$embeds added.verified against source$embeds parameter was added.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/pluggable.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.