Email Types Reference
Every email Benecaster sends carries a type string — a stable identifier used to target that one email through the filter and action families below. This page is the developer-facing index of those strings. For what each email says and when a podcaster would turn it off, see Automated Emails.
Type strings are stable public API. They will not change between minor versions.
Core Types
Sent from the podcaster’s WordPress site via EmailQueue.
| Type string | Sent when |
|---|---|
welcome |
A subscriber’s feed token is generated for the first time |
token_reset |
A feed token is reset, by admin or by the subscriber |
token_revoked |
A subscriber’s access is revoked ⚠ see note below |
tier_change |
A subscriber’s tier is updated — upgrade, downgrade, or admin change |
auto_upgrade_fired |
Admin email: the daily validation cycle confirms a scheduled plan auto-upgrade took effect |
donation_thank_you |
A Listener Support donation is logged and a donor email address is available |
⚠ token_revoked is registered but does not currently send. The type is present in EmailTypeRegistry and appears in the admin email settings UI, but no template exists and nothing listens to the dispatch action. Treat it as reserved: filters targeting it will not fire, because no email is queued. Tracked as a plugin bug.
Add-on Types
Not registered, and not present in email settings, unless the add-on is active.
| Type string | Add-on |
|---|---|
broadcast |
Email Editor |
episode_notification |
Email Editor |
analytics_digest_daily |
Analytics Dashboard |
analytics_digest_weekly |
Analytics Dashboard |
analytics_digest_monthly |
Analytics Dashboard |
Add-ons may register further types through benecaster_managed_email_types. Those follow the same snake_case convention and are documented by the add-on that owns them.
Not Plugin Types
License server emails — threshold_warning, threshold_crossed, plan_bumped, downgrade_available, the payment-failure grace sequence (day 0, 10, 20, 29 and post-cutoff recovery), and similar — are dispatched from benecaster.com, not through the plugin’s EmailQueue. They fire none of the hooks below, never appear in the queue, and cannot be filtered or templated. If a filter you expect to fire never does, check whether the email actually originates on the site.
The payment-failure sequence moved to the license server deliberately: it addresses the account holder’s billing rather than any one site, and a license covering several sites should produce one message per event rather than one from each install. The plugin retains the local consequences of a payment failure — feed behavior during the grace window, the day-30 token revoke, and post-recovery restoration — and exposes them through benecaster_license_grace_started, benecaster_license_payment_grace_hard_cutoff, and benecaster_license_payment_grace_recovered. Hook those for local observability; there is no plugin-side hook for the emails themselves.
Filter Families
Every filter below has a shared form and a type-specific variant. The pattern is {filter}_{$email_type} — so benecaster_email_subject_welcome targets only the welcome email.
| Shared filter | Type-specific variant | Filters |
|---|---|---|
benecaster_email_should_send |
benecaster_email_should_send_{type} |
Whether the email dispatches at all |
benecaster_email_subject |
benecaster_email_subject_{type} |
Subject line |
benecaster_email_body_html |
benecaster_email_body_html_{type} |
HTML body |
benecaster_email_body_text |
benecaster_email_body_text_{type} |
Plain-text body |
benecaster_email_from_name |
benecaster_email_from_name_{type} |
Sender name |
benecaster_email_from_address |
benecaster_email_from_address_{type} |
Sender address |
benecaster_email_merge_tags |
benecaster_email_merge_tags_{type} |
Resolved merge tag map |
Type-specific variants take one fewer parameter — $email_type is omitted, since it’s encoded in the hook name. Everything else, including return type, is unchanged.
Use the type-specific variant when your callback targets one template. Use the shared filter when one callback handles several types differently.
Actions
| Shared action | Type-specific variant | Fires |
|---|---|---|
benecaster_before_email_send |
benecaster_before_email_send_{type} |
Immediately before dispatch |
benecaster_after_email_send |
benecaster_after_email_send_{type} |
Immediately after dispatch |
Suppression and Transactional Status
benecaster_email_should_send will suppress any type, but that does not make suppressing any type advisable.
Transactional emails should never be suppressed. welcome and token_reset are the delivery mechanism for feed URLs — suppress them and subscribers simply never receive access, with nothing surfaced to explain why. Billing emails carry the same weight for compliance reasons.
broadcast is the only genuinely marketing-class type in the list, and the only one affected by unsubscribe preference. Transactional types are exempt from unsubscribe suppression by design — a subscriber who opted out of broadcasts still receives their feed URL.
If your goal is to route an email through your own service rather than stop it, suppress with this filter and send it yourself in the same callback — don’t suppress and assume something else will deliver it.
Merge Tags
Available tags vary by type. See Email Merge Tags for the full catalog, including the global set available to every type and how to register your own.