Spin Wheel

⌘K
  2. Home
  4. Spin Wheel
  6. Hooks & Filters (Deve...
  8. Before email is sent (uspw_before_send_winner_email)

Before email is sent (uspw_before_send_winner_email)

uspw_before_send_winner_email

Description

Fires before the winner email is sent, allowing developers to modify email parameters, customize content, or route emails through different services.

Hook Type: Filter
Since: 1.0.0

Parameters

ParameterTypeDescription
$email_argsarrayEmail parameters (to, subject, message, headers)
$dataarrayEntry data
$campaign_idintThe ID of the spin wheel campaign

Usage

add_filter( 'uspw_before_send_winner_email', 'my_email_customization', 10, 3 );
function my_email_customization( $email_args, $data, $campaign_id ) {
    // Modify $email_args as needed
    return $email_args;
}

Real-World Examples

Example 1: Translate Emails Based on User Location

Automatically translate email content based on the user’s country or language preference.

add_action( 'uspw_before_send_winner_email', 'translate_winner_email', 10, 3 );
function translate_winner_email( &$email_args, $data, $campaign_id ) {
    $country = $data['country'] ?? '';
    
    // Define translations
    $translations = [
        'ES' => [ // Spain
            'subject' => '¡Felicidades! Has ganado un premio',
            'greeting' => 'Hola',
            'message' => 'Felicidades por ganar',
            'code_label' => 'Tu código de cupón',
            'footer' => 'Gracias por participar'
        ],
        'FR' => [ // France
            'subject' => 'Félicitations ! Vous avez gagné un prix',
            'greeting' => 'Bonjour',
            'message' => 'Félicitations pour avoir gagné',
            'code_label' => 'Votre code promo',
            'footer' => 'Merci de votre participation'
        ],
        'DE' => [ // Germany
            'subject' => 'Glückwunsch! Sie haben einen Preis gewonnen',
            'greeting' => 'Hallo',
            'message' => 'Herzlichen Glückwunsch zum Gewinn',
            'code_label' => 'Ihr Gutscheincode',
            'footer' => 'Vielen Dank für Ihre Teilnahme'
        ]
    ];
    
    if ( isset( $translations[ $country ] ) ) {
        $trans = $translations[ $country ];
        
        // Update subject
        $email_args['subject'] = $trans['subject'];
        
        // Update message with translated content
        $email_args['message'] = sprintf(
            '<p>%s %s,</p><p>%s <strong>%s</strong>!</p><p>%s: <strong>%s</strong></p><p>%s</p>',
            $trans['greeting'],
            $data['name'] ?? '',
            $trans['message'],
            $data['coupon_title'] ?? '',
            $trans['code_label'],
            $data['coupon_code'] ?? '',
            $trans['footer']
        );
    }
}

Example 2: Route High-Value Winners to Transactional Email Service

Send high-value winner emails through a premium transactional email service like SendGrid.

add_action( 'uspw_before_send_winner_email', 'route_high_value_emails', 10, 3 );
function route_high_value_emails( &$email_args, $data, $campaign_id ) {
    $prize_value = floatval( $data['prize_value'] ?? 0 );
    
    // Use SendGrid for prizes over $50
    if ( $prize_value >= 50 ) {
        $sendgrid_api_key = get_option( 'sendgrid_api_key' );
        
        if ( $sendgrid_api_key ) {
            // Prepare SendGrid payload
            $sendgrid_data = [
                'personalizations' => [
                    [
                        'to' => [
                            [
                                'email' => $email_args['to'],
                                'name' => $data['name'] ?? ''
                            ]
                        ],
                        'dynamic_template_data' => [
                            'name' => $data['name'] ?? '',
                            'prize_label' => $data['coupon_title'] ?? '',
                            'prize_value' => $prize_value,
                            'coupon_code' => $data['coupon_code'] ?? '',
                            'campaign_name' => get_the_title( $campaign_id )
                        ]
                    ]
                ],
                'from' => [
                    'email' => '[email protected]',
                    'name' => get_bloginfo( 'name' )
                ],
                'template_id' => 'd-xxxxxxxxxxxxx' // Your SendGrid template ID
            ];
            
            // Send via SendGrid
            $response = wp_remote_post( 'https://api.sendgrid.com/v3/mail/send', [
                'headers' => [
                    'Authorization' => 'Bearer ' . $sendgrid_api_key,
                    'Content-Type' => 'application/json'
                ],
                'body' => wp_json_encode( $sendgrid_data )
            ] );
            
            // Prevent wp_mail from sending
            if ( ! is_wp_error( $response ) && wp_remote_retrieve_response_code( $response ) === 202 ) {
                // Clear email_args to prevent wp_mail from sending
                $email_args['to'] = '';
            }
        }
    }
}

Example 3: Add Personalized Product Recommendations

Include personalized product recommendations in the winner email based on prize value.

add_action( 'uspw_before_send_winner_email', 'add_product_recommendations', 10, 3 );
function add_product_recommendations( &$email_args, $data, $campaign_id ) {
    if ( ! class_exists( 'WooCommerce' ) ) {
        return;
    }
    
    $prize_value = floatval( $data['prize_value'] ?? 0 );
    
    // Get products in similar price range
    $args = [
        'post_type' => 'product',
        'posts_per_page' => 3,
        'meta_query' => [
            [
                'key' => '_price',
                'value' => [ $prize_value * 0.8, $prize_value * 1.5 ],
                'compare' => 'BETWEEN',
                'type' => 'NUMERIC'
            ]
        ],
        'orderby' => 'rand'
    ];
    
    $products = get_posts( $args );
    
    if ( $products ) {
        $recommendations_html = '<h3>You might also like:</h3><div style="margin: 20px 0;">';
        
        foreach ( $products as $product_post ) {
            $product = wc_get_product( $product_post->ID );
            
            $recommendations_html .= sprintf(
                '<div style="margin-bottom: 15px; padding: 10px; border: 1px solid #ddd;">
                    <h4>%s</h4>
                    <p>%s</p>
                    <p><strong>Price: %s</strong></p>
                    <a href="%s" style="background: #0073aa; color: white; padding: 10px 20px; text-decoration: none; display: inline-block;">View Product</a>
                </div>',
                $product->get_name(),
                wp_trim_words( $product->get_short_description(), 20 ),
                $product->get_price_html(),
                get_permalink( $product->get_id() )
            );
        }
        
        $recommendations_html .= '</div>';
        
        // Append to email message
        $email_args['message'] .= $recommendations_html;
    }
}

Example 4: Add Dynamic Expiration Timer

Include a countdown timer showing when the coupon expires.

add_action( 'uspw_before_send_winner_email', 'add_expiration_timer', 10, 3 );
function add_expiration_timer( &$email_args, $data, $campaign_id ) {
    // Get coupon expiration (assuming 7 days from now)
    $expiration_date = date( 'F j, Y', strtotime( '+7 days' ) );
    $expiration_timestamp = strtotime( '+7 days' );
    
    // Calculate days remaining
    $days_remaining = ceil( ( $expiration_timestamp - time() ) / DAY_IN_SECONDS );
    
    // Add urgency message
    $urgency_html = sprintf(
        '<div style="background: #fff3cd; border: 2px solid #ffc107; padding: 20px; margin: 20px 0; text-align: center;">
            <h3 style="color: #856404; margin: 0 0 10px 0;">⏰ Limited Time Offer!</h3>
            <p style="font-size: 18px; margin: 0; color: #856404;">
                Your coupon expires in <strong style="font-size: 24px; color: #d9534f;">%d days</strong>
            </p>
            <p style="margin: 10px 0 0 0; color: #856404;">Expires on: <strong>%s</strong></p>
        </div>',
        $days_remaining,
        $expiration_date
    );
    
    // Insert after the main message
    $email_args['message'] = str_replace(
        '</body>',
        $urgency_html . '</body>',
        $email_args['message']
    );
    
    // Update subject to add urgency
    $email_args['subject'] .= sprintf( ' - Expires in %d Days!', $days_remaining );
}

Example 5: A/B Test Email Templates

Test different email templates and track which performs better.

add_action( 'uspw_before_send_winner_email', 'ab_test_email_templates', 10, 3 );
function ab_test_email_templates( &$email_args, $data, $campaign_id ) {
    // Determine variant based on email hash (consistent per user)
    $email_hash = md5( $email_args['to'] );
    $variant = ( hexdec( substr( $email_hash, 0, 1 ) ) % 2 === 0 ) ? 'A' : 'B';
    
    if ( $variant === 'A' ) {
        // Template A: Professional and formal
        $email_args['subject'] = sprintf(
            'Congratulations! You\'ve Won %s',
            $data['coupon_title'] ?? 'a Prize'
        );
        
        $template_a = '
        <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
            <div style="background: #f8f9fa; padding: 20px; text-align: center;">
                <h1 style="color: #333;">Congratulations!</h1>
            </div>
            <div style="padding: 30px; background: white;">
                <p>Dear ' . esc_html( $data['name'] ?? 'Valued Customer' ) . ',</p>
                <p>We are pleased to inform you that you have won <strong>' . esc_html( $data['coupon_title'] ?? '' ) . '</strong>.</p>
                <div style="background: #e9ecef; padding: 20px; margin: 20px 0; text-align: center;">
                    <p style="margin: 0; font-size: 14px; color: #666;">Your Coupon Code</p>
                    <p style="margin: 10px 0 0 0; font-size: 24px; font-weight: bold; color: #0073aa;">' . esc_html( $data['coupon_code'] ?? '' ) . '</p>
                </div>
                <p>Thank you for participating.</p>
            </div>
        </div>';
        
        $email_args['message'] = $template_a;
        
    } else {
        // Template B: Exciting and casual
        $email_args['subject'] = sprintf(
            '🎉 You Won! Claim Your %s Now!',
            $data['coupon_title'] ?? 'Prize'
        );
        
        $template_b = '
        <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
            <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 40px; text-align: center;">
                <h1 style="color: white; font-size: 32px; margin: 0;">🎉 WINNER! 🎉</h1>
            </div>
            <div style="padding: 30px; background: white;">
                <p style="font-size: 18px;">Hey ' . esc_html( $data['name'] ?? 'there' ) . '! 🎊</p>
                <p style="font-size: 16px;">You just won <strong style="color: #667eea;">' . esc_html( $data['coupon_title'] ?? '' ) . '</strong>! How awesome is that?!</p>
                <div style="background: #f8f9fa; border-left: 4px solid #667eea; padding: 20px; margin: 20px 0;">
                    <p style="margin: 0; font-size: 12px; text-transform: uppercase; color: #666;">Your Code</p>
                    <p style="margin: 10px 0 0 0; font-size: 28px; font-weight: bold; color: #667eea; letter-spacing: 2px;">' . esc_html( $data['coupon_code'] ?? '' ) . '</p>
                </div>
                <p>Don\'t wait - use it now! 🚀</p>
            </div>
        </div>';
        
        $email_args['message'] = $template_b;
    }
    
    // Log the variant for tracking
    global $wpdb;
    $table = $wpdb->prefix . 'spin_email_ab_test';
    $wpdb->insert( $table, [
        'email' => $email_args['to'],
        'variant' => $variant,
        'campaign_id' => $campaign_id,
        'sent_at' => current_time( 'mysql' )
    ] );
}

Notes

  • The $email_args parameter is passed by reference, so modifications will affect the email that gets sent.
  • The $email_args array contains: to, subject, message, and headers.
  • To prevent the default email from sending (e.g., when using a third-party service), set $email_args['to'] = ''.
  • Perfect for email customization, translation, A/B testing, and routing to external email services.
  • Changes made here affect the email sent via wp_mail().

How can we help?