Skip to main content

Email customization

Overview​

Password reset emails can be customized through plugin settings for basic changes or WordPress filters for advanced HTML templates. The plugin sends HTML emails with template variables that are replaced with actual user data.

Basic customization (Settings)​

The easiest way to customize emails is through General settings in the WordPress admin.

Email subject​

Setting: Email Subject
Default: "Account Password Reset"
Template variables: {username}, {email}

Example:

Password Reset Request for {username}

Email body​

Setting: Email Message
Default: Standard WordPress reset email text
Template variables: {username}, {reset_link}, {email}

Example:

<p>Hi {username},</p>

<p>Someone requested a password reset for your account at our site.</p>

<p>If this was you, click the link below to reset your password:</p>

<p>{reset_link}</p>

<p>If you didn't request this, you can safely ignore this email.</p>

<p>Thanks,<br>
The Team</p>

Sender information​

From Name: Name displayed as email sender
From Email: Email address used as sender

Example:

Reset link text​

Setting: Reset Link Text
Purpose: Custom text for the reset link instead of showing the full URL

Example:

Click here to reset your password

This creates: <a href="{reset_link}">Click here to reset your password</a>

Template variables​

Three variables are available in email subject and body:

{username}​

Replaced with: User's WordPress login name
Use in: Subject and body

Example:

Hi {username}, we received a password reset request for your account.

Replaced with: Full password reset URL with key and user ID
Use in: Body only

The link includes:

  • Base URL (reset password page)
  • somresetpass=true parameter
  • key parameter (reset key)
  • uid parameter (user ID)

Example URL:

https://example.com/reset-password/?somresetpass=true&key=abc123&uid=45

{email}​

Replaced with: User's email address
Use in: Subject and body

Example:

This email was sent to {email}. If this is not your email address, please ignore this message.

Advanced customization (Filters)​

For complete control over email content, use WordPress filters in your theme's functions.php.

Email subject filter​

Filter: somfrp_retrieve_password_title
Parameters: $title, $user_login, $user_data

Example:

add_filter( 'somfrp_retrieve_password_title', 'custom_reset_email_subject', 10, 3 );
function custom_reset_email_subject( $title, $user_login, $user_data ) {
    $site_name = get_bloginfo( 'name' );
    return sprintf( '[%s] Password Reset for %s', $site_name, $user_login );
}

Email body filter​

Filter: somfrp_retrieve_password_message
Parameters: $message, $key, $user_login, $user_data

Example:

add_filter( 'somfrp_retrieve_password_message', 'custom_reset_email_body', 10, 4 );
function custom_reset_email_body( $message, $key, $user_login, $user_data ) {
    $reset_url = som_get_lost_password_url() . '?somresetpass=true&key=' . $key . '&uid=' . $user_data->ID;
    
    $message = '<html><body>';
    $message .= '<div style="max-width: 600px; margin: 0 auto; font-family: Arial, sans-serif;">';
    $message .= '<h2 style="color: #333;">Password Reset Request</h2>';
    $message .= '<p>Hello ' . esc_html( $user_login ) . ',</p>';
    $message .= '<p>We received a request to reset your password. Click the button below to create a new password:</p>';
    $message .= '<p style="text-align: center;">';
    $message .= '<a href="' . esc_url( $reset_url ) . '" style="display: inline-block; padding: 12px 24px; background: #0073aa; color: #fff; text-decoration: none; border-radius: 4px;">Reset Password</a>';
    $message .= '</p>';
    $message .= '<p style="color: #666; font-size: 14px;">If you didn\'t request this, you can safely ignore this email.</p>';
    $message .= '<p style="color: #666; font-size: 14px;">This link will expire in 24 hours.</p>';
    $message .= '</div>';
    $message .= '</body></html>';
    
    return $message;
}

HTML email templates​

The plugin sends HTML emails by default. You can create fully styled HTML templates.

Complete HTML email example​

add_filter( 'somfrp_retrieve_password_message', 'branded_reset_email', 10, 4 );
function branded_reset_email( $message, $key, $user_login, $user_data ) {
    $reset_url = som_get_lost_password_url() . '?somresetpass=true&key=' . $key . '&uid=' . $user_data->ID;
    $site_name = get_bloginfo( 'name' );
    $logo_url = get_stylesheet_directory_uri() . '/images/logo.png';
    
    ob_start();
    ?>
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Password Reset</title>
    </head>
    <body style="margin: 0; padding: 0; background-color: #f4f4f4;">
        <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4;">
            <tr>
                <td align="center" style="padding: 40px 0;">
                    <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
                        <!-- Header -->
                        <tr>
                            <td align="center" style="padding: 40px 40px 20px;">
                                <img src="<?php echo esc_url( $logo_url ); ?>" alt="<?php echo esc_attr( $site_name ); ?>" style="max-width: 200px;">
                            </td>
                        </tr>
                        
                        <!-- Content -->
                        <tr>
                            <td style="padding: 20px 40px;">
                                <h2 style="color: #333; font-size: 24px; margin: 0 0 20px;">Password Reset Request</h2>
                                <p style="color: #666; font-size: 16px; line-height: 1.5; margin: 0 0 20px;">
                                    Hello <strong><?php echo esc_html( $user_login ); ?></strong>,
                                </p>
                                <p style="color: #666; font-size: 16px; line-height: 1.5; margin: 0 0 20px;">
                                    We received a request to reset the password for your account at <?php echo esc_html( $site_name ); ?>.
                                </p>
                                <p style="color: #666; font-size: 16px; line-height: 1.5; margin: 0 0 30px;">
                                    Click the button below to create a new password:
                                </p>
                            </td>
                        </tr>
                        
                        <!-- Button -->
                        <tr>
                            <td align="center" style="padding: 0 40px 30px;">
                                <a href="<?php echo esc_url( $reset_url ); ?>" style="display: inline-block; padding: 14px 40px; background-color: #0073aa; color: #ffffff; text-decoration: none; border-radius: 4px; font-size: 16px; font-weight: 600;">Reset Password</a>
                            </td>
                        </tr>
                        
                        <!-- Footer -->
                        <tr>
                            <td style="padding: 20px 40px 40px; border-top: 1px solid #e0e0e0;">
                                <p style="color: #999; font-size: 14px; line-height: 1.5; margin: 0 0 10px;">
                                    If you didn't request this password reset, you can safely ignore this email. Your password will remain unchanged.
                                </p>
                                <p style="color: #999; font-size: 14px; line-height: 1.5; margin: 0;">
                                    This link will expire in 24 hours for security reasons.
                                </p>
                            </td>
                        </tr>
                    </table>
                </td>
            </tr>
        </table>
    </body>
    </html>
    <?php
    return ob_get_clean();
}

Multi-language emails​

Send emails in the user's language using WPML or Polylang:

add_filter( 'somfrp_retrieve_password_message', 'multilang_reset_email', 10, 4 );
function multilang_reset_email( $message, $key, $user_login, $user_data ) {
    $reset_url = som_get_lost_password_url() . '?somresetpass=true&key=' . $key . '&uid=' . $user_data->ID;
    
    // Get user's language (example for WPML)
    $user_lang = get_user_meta( $user_data->ID, 'icl_admin_language', true );
    if ( empty( $user_lang ) ) {
        $user_lang = 'en';
    }
    
    // Switch to user's language
    if ( function_exists( 'icl_switch_language' ) ) {
        icl_switch_language( $user_lang );
    }
    
    // Build message in user's language
    $message = '<p>' . __( 'Hello', 'your-theme' ) . ' ' . esc_html( $user_login ) . ',</p>';
    $message .= '<p>' . __( 'Click the link below to reset your password:', 'your-theme' ) . '</p>';
    $message .= '<p><a href="' . esc_url( $reset_url ) . '">' . __( 'Reset Password', 'your-theme' ) . '</a></p>';
    
    return $message;
}

Conditional email content​

Customize emails based on user role or other criteria:

add_filter( 'somfrp_retrieve_password_message', 'role_based_reset_email', 10, 4 );
function role_based_reset_email( $message, $key, $user_login, $user_data ) {
    $reset_url = som_get_lost_password_url() . '?somresetpass=true&key=' . $key . '&uid=' . $user_data->ID;
    
    // Check user role
    if ( in_array( 'administrator', $user_data->roles ) ) {
        $message = '<p>Admin password reset request for ' . esc_html( $user_login ) . '</p>';
        $message .= '<p><strong>Security Notice:</strong> This is an administrator account.</p>';
    } elseif ( in_array( 'customer', $user_data->roles ) ) {
        $message = '<p>Hi ' . esc_html( $user_login ) . ',</p>';
        $message .= '<p>Need help? Contact our support team at [email protected]</p>';
    } else {
        $message = '<p>Hi ' . esc_html( $user_login ) . ',</p>';
    }
    
    $message .= '<p><a href="' . esc_url( $reset_url ) . '">Reset Password</a></p>';
    
    return $message;
}

Email testing​

Test your custom emails:

Method 1: Use a test account​

  1. Create a test user account
  2. Request password reset for that account
  3. Check the email received
  4. Verify all links work correctly

Method 2: Use email testing plugin​

Install an email testing plugin like "WP Mail Logging" to capture and preview emails without sending them.

Method 3: Use email testing service​

Use services like Mailtrap or MailHog to capture test emails in a development environment.

Common email scenarios​

Scenario 1: Add company branding​

Include logo, colors, and footer with company information.

Scenario 2: Add security warnings​

For sensitive sites, add warnings about suspicious activity or security tips.

Scenario 3: Include support contact​

Add support email or phone number for users who need help.

Scenario 4: Add expiration notice​

Remind users that the reset link expires in 24 hours.

Scenario 5: Add alternative method​

Provide alternative password reset method (phone support, in-person verification).

Troubleshooting​

Emails not sending​

See Email troubleshooting guide for detailed solutions.

HTML not rendering​

Problem: Email displays HTML code instead of formatted content.

Solution: Ensure email content type is set to HTML. The plugin handles this automatically, but some email plugins may interfere.

Template variables not replaced​

Problem: Email shows {username} instead of actual username.

Solution: Verify you're using the correct variable names: {username}, {reset_link}, {email}. Variables are case-sensitive.

Custom filter not working​

Problem: Custom email filter doesn't apply.

Solution:

  • Verify filter name is correct: somfrp_retrieve_password_message
  • Check filter priority (default is 10)
  • Ensure code is in active theme's functions.php
  • Clear all caches

Best practices​

Keep it simple​

Don't overcomplicate email templates. Simple, clear emails have better deliverability.

Test thoroughly​

Test emails on multiple email clients:

  • Gmail
  • Outlook
  • Apple Mail
  • Mobile email apps

Use inline CSS​

Email clients have limited CSS support. Use inline styles instead of external stylesheets.

Provide plain text alternative​

Some users prefer plain text emails. Consider providing a plain text version.

Include unsubscribe option​

For marketing emails (not password resets), include an unsubscribe link.

Monitor deliverability​

Use email delivery monitoring to ensure emails reach users' inboxes.

What's next​