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, stored on the queue row and applied as a From: header when the row 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

Whether the message was queued. true says nothing about delivery, and on a copy of the site the message is held, not sent.

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

It queues the message; it does not send it. It writes one ad_hoc row to the email queue at priority 1, which a live site sends within seconds, and a row to the email log. On a copy of the site (where benecaster_is_production_site() is false) the message is held and logged held, and dropped unsent after three days, like every other Benecaster email.

It does not gate or suppress. No should_send gate runs, so an unsubscribed recipient is not filtered out, and no before- or after-send action fires. 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 pipeline do its job.

One call is one message: a comma-separated $to is queued as one row and sent as one email.

$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.

The identity and header filters fire in your own request, when the message is queued, and the result is stored on the queue row for the later send. The type passed to them 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 is ad_hoc rather than custom 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 →