Skip to main content

benecaster_find_audience_user_ids()

Membership Free 
benecaster_find_audience_user_ids( int $show_id, string $audience ): array

Resolves a broadcast audience slug to the WordPress user IDs it reaches — the public entry point for answering “who would this send go to?” without pulling anything out of the service container.

Built-in audiences:

  • paying — paying subscribers only, the same definition as benecaster_count_paying_subscribers(): a token type Benecaster doesn’t exempt (PAYING_EXEMPT_TOKEN_TYPES, follower today — a deny list, not token_type = 'subscriber') on a tier that isn’t free. Excludes followers and bridge members on a free tier; includes any other token type, including one an add-on defines, on a paid tier.

  • followers — direct followers only.

  • all — every active token holder for the show.

  • tier:SLUG — active holders of one tier, e.g. tier:gold.

A tier: slug must match one of the show’s configured tier slugs exactly, and the match is case-sensitive. The show’s tiers are its Tier Mapping on a membership-plugin show, or Memberships → Tiers on a built-in-membership show. tier:Gold does not find gold. A show’s public tier is a valid slug, but nobody holds a token on it, so it resolves empty.

tier:follower does not reach your followers. Follower tokens carry the tier slug follower, and no tier is configured with that slug on a normal install, in Tier Mapping or among a built-in show’s tiers, so it resolves empty. Use followers.

Anything else resolves to an empty array before the benecaster_broadcast_audience_user_ids filter fires, which is how an add-on defines an audience of its own — the callback receives an empty list and returns whatever it likes. The filter runs for built-in audiences too, so a callback can equally subtract from one: opt-outs, suppression lists, a test-group restriction.

Parameters

Name Type Default Required Description
show_id int — Yes WordPress post ID of the show.
audience string — Yes Audience slug: paying, followers, all, tier:SLUG, or a slug an add-on defines.

Return Value

Type: array

Deduplicated WordPress user IDs. Order is not guaranteed. Empty for an audience nobody is in, and for one that does not exist.

Example

$gold = benecaster_find_audience_user_ids( $show_id, 'tier:gold' );

foreach ( $gold as $user_id ) {
    // Hand off to the email queue, an ESP API call, an export sheet.
}

Hooks Fired

Notes

An empty array is not an error, and is never distinguishable from one. A tier nobody holds, a slug the show has not configured, a typo, and an audience whose members were all revoked this morning all return []. A caller that needs to tell those apart has to check the tier map itself — so do not report "no subscribers on that tier" on the strength of this return value alone, because a mistyped slug looks exactly the same.

Safe to call from inside a benecaster_broadcast_audience_user_ids callback. Asking for the audience you are currently resolving returns Benecaster's own answer rather than recursing; asking for a different one filters normally.

Unsubscribe suppression is applied separately, further down the send path. A user ID in this list is not a promise that the person will receive the email. To send one message to one or more audiences, use benecaster_send_broadcast().

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