benecaster_email_editor_get_engagement()
benecaster_email_editor_get_engagement( int $show_id, array $args = [] ): ?array
How many people each of a show’s episode notifications and broadcasts reached, opened and clicked. It is the one supported way to read the Email Editor’s open and click records, and the one the Analytics Dashboard uses: never query the tables.
Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
show_id |
int |
— | Yes | The show. |
args |
array |
[] |
No | type ('' for both, episode_notification or broadcast), send_ids (int[]), since and until (UTC Y-m-d H:i:s, compared with the send's time; any other format is ignored), by_tier (bool, default false). |
Return Value
Type:
?array
Each send, newest first: type, send_id (the episode, or the broadcast's id), sent_at (UTC, when the first recipient was queued), recipients, opened (recipients with at least one open), opens (every open), clicked and clicks; with by_tier, a by_tier map of tier slug ('' for followers) to those five counts. [] when the Email Editor is on and nothing was sent; null when it is not on for the show, and always for show 0.
Example
if ( function_exists( 'benecaster_email_editor_get_engagement' ) ) {
$sends = benecaster_email_editor_get_engagement( $show_id, [ 'type' => 'broadcast' ] );
if ( null === $sends ) {
// The Email Editor is not on for this show: show a placeholder instead.
}
}
Hooks Fired
Notes
Aggregates only. No user id, address or name is ever returned.
Opens are directional. Apple Mail fetches every tracking pixel when the mail arrives, and some mail apps block images, so show that caveat beside any open rate.
A recipient is counted when Benecaster queues their email, so suppressed sends, previews and test sends are never in it. Nothing is counted while the Email Editor is not on for the send's show, and a show switched off keeps its records. They are kept 730 days after the send, changed with benecaster_email_editor_engagement_retention_days.
It is defined on every request, whether or not the Email Editor is on for any show. Guard
calls with function_exists(), since the Email Editor may not be installed.
Need this built rather than just documented? See our services →