Skip to main content

Invite a guest to the Guest portal, or stop their link, from code, and change the invitation email

Premium Intermediate Guest Manager

The Guest portal lets a podcaster email a guest a private link to suggest changes to their own profile; every change waits for the podcaster’s approval. The guest gets no WordPress account and no password: the link is the only credential.

  • The switch is the site option benecaster_guest_manager_portal ('1' on; anything else, or missing, off), the Guest portal box on Benecaster → Guests. PUT, PATCH /wp-json/benecaster-guest-manager/v1/settings takes { portal: bool } beside directory (see Switch on, restyle or extend the public guest directory), with the same accepted values and the same 400 benecaster_guest_manager_invalid_setting (data.field portal); GET /settings answers { directory, directory_url, portal }. The settings hooks fire for it as for the directory. Switching it off stops every link at once without deleting one: a link that has not expired works again once it is switched back on.
  • GET /guests/{id}/invitation answers { enabled, has_email, invitation }: whether the portal is on, whether the guest has a saved email, and the live link as { expires, expires_display } (ISO 8601 UTC, and the site’s date and time format and timezone), or null. Reading an expired invitation deletes it.
  • POST /guests/{id}/invitation (Invite to Edit Profile, Send a New Link) makes a new key, emails the guest the link and stores it, replacing any earlier link, which stops working; it answers as GET. The link is /guests/{post_name}/edit/?key={64 hex} (under plain permalinks, the guest page’s address plus &benecaster_guest_edit=1&key=…) and works for 14 days. Refusals: 404 benecaster_guest_manager_not_found, 409 benecaster_guest_manager_portal_off, 400 benecaster_guest_manager_no_email, and 500 benecaster_guest_manager_invitation_not_sent when wp_mail() fails, which stores nothing, so the earlier link still works.
  • DELETE /guests/{id}/invitation (Stop Access) ends the link, the portal on or off; it answers as GET.
  • All three are admin only (manage_options through benecaster_rest_permission_admin(), with the X-WP-Nonce header), with no show: a guest is the site’s.
  • The key is never in a response, a hook’s arguments or the database. It is in the email and nowhere else; the guest’s private meta holds only its SHA-256 hash and when it expires.

The email is plain text, sent with wp_mail() to the guest’s Email, with the site’s title as the sender’s name.

  • benecaster_guest_manager_invitation_email_subject( string $subject, int $guest_id, string $link ) and benecaster_guest_manager_invitation_email_message( string $message, int $guest_id, string $link, string $expires_gmt ) filter it. $link is the guest’s credential: put it in the message, never in a log, an option or another request.
  • benecaster_guest_manager_before_invite_guest( int $guest_id ) fires before the key is made and emailed; benecaster_guest_manager_after_invite_guest( int $guest_id, string $expires_gmt ) once it is emailed and stored, not when the email failed.
  • benecaster_guest_manager_before_stop_guest_access( int $guest_id ) and benecaster_guest_manager_after_stop_guest_access( int $guest_id, bool $had_link ) fire around Stop Access.

Code

<?php
// Invite a guest from code, e.g. when a booking form confirms them.
$request = new WP_REST_Request( 'POST', '/benecaster-guest-manager/v1/guests/' . $guest_id . '/invitation' );
$response = rest_do_request( $request );
if ( $response->is_error() ) {
    error_log( 'Guest portal invite refused: ' . $response->as_error()->get_error_code() );
}

// Add the show's booking contact to the bottom of every invitation.
add_filter( 'benecaster_guest_manager_invitation_email_message', static function ( string $message ): string {
    return $message . "\n\n" . __( 'Questions? Reply to bookings@example.com.', 'my-plugin' );
} );

View on GitHub →

Hooks Used

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