Skip to main content

benecaster_mail()

Utilities Free 
benecaster_mail( int $show_id, string $to, string $subject, string $message, array $headers = [] ): bool

Sends an ad-hoc email carrying Benecaster’s sender identity — a drop-in for wp_mail() in add-on code. Use it for one-off mail that is not a registered email type — an operator alert, an internal report, a one-off nudge — but that should still look to the recipient as though it came from the podcast rather than from WordPress.

A raw wp_mail() call gets none of Benecaster’s sender overrides, and this is the leak the function exists to close. They are not bound as global wp_mail_from / wp_mail_from_name / wp_mail_content_type filters — nothing in the plugin registers those. Sender identity is computed inside the dispatch pipeline and applied when the message is sent. Call wp_mail() directly from add-on code and your message goes out as wordpress@yoursite.com.

It applies, in the same order the pipeline does: benecaster_email_from_name, benecaster_email_from_address and benecaster_email_headers, each followed by its _ad_hoc type-specific variant. Defaults are the site’s blogname and admin_email.

Parameters

Name Type Default Required Description
show_id int — Yes Show post ID, passed to the identity filters as context. 0 when there is none. It does not select a per-show sender — see the notes.
to string — Yes Recipient address.
subject string — Yes Subject line.
message string — Yes Message body. HTML by default.
headers array [] No Extra headers. A From: line here is ignored — see the notes.

Return Value

Type: bool

wp_mail()'s own return value — whether the message was handed off for delivery, which is not a guarantee that it arrived.

Example

benecaster_mail(
    $show_id,
    (string) get_option( 'admin_email' ),
    __( 'Your export is ready', 'my-addon' ),
    sprintf(
        '<p>' . esc_html__( 'Your export is ready: %s', 'my-addon' ) . '</p>',
        esc_url( $download_url )
    ),
    [ 'Reply-To: producer@example.com' ]
);

Notes

This does not queue, log, gate or suppress. It is a direct send. No should_send gate runs, so an unsubscribed recipient is not filtered out, and nothing lands in benecaster_email_log. Anything sent to subscribers in bulk, or anything a subscriber can opt out of, belongs in benecaster_send_email() instead — register the type and let the queue do its job.

$show_id does not select a per-show sender — there is no such setting. The from-name defaults to the site-wide blogname. The show is passed to the filters so that an add-on can vary identity per show, which is the only reason it is in the signature. Do not expect a show to have its own configured from-name; none does.

A From: header you supply is dropped, exactly as the queue processor drops one, so the message never goes out with two. A message with two From lines is malformed and lands differently in every mail server.

Because this sends immediately, benecaster_email_headers fires in your own request here — unlike the queued path, where it fires at enqueue time and the headers are stored for a later cron send. The type passed to the identity and header filters is ad_hoc.

ad_hoc is a reserved email type slug — never register it through benecaster_managed_email_types. Every message this function sends carries that type, so registering it would fire your own benecaster_email_from_name_ad_hoc, benecaster_email_from_address_ad_hoc and benecaster_email_headers_ad_hoc callbacks for every ad-hoc message anywhere on the site, not just for yours. The slug was custom until 2026-09-02 and was renamed for exactly this reason: custom is the single most likely name a third party would pick for their own type.

Need this built rather than just documented? See our services →

Powered by