Add SendGrid category tracking in API delivery mode

Free Intermediate Since v1.0.0

Tags every outbound Benecaster email with a SendGrid category and custom arguments when WP Mail SMTP is configured with the SendGrid API mailer (Settings → WP Mail SMTP → Mailer → SendGrid → Mailer Type = API).

API mode only. When SendGrid is used in SMTP relay mode, use the sibling recipe Add SendGrid category tracking to all emails (the X-SMTPAPI header approach) instead. Hook both in parallel if the operator may switch delivery modes.

The two-filter approach is necessary because WP Mail SMTP’s get_body filter fires deep inside the SendGrid Mailer class with no access to Benecaster context. The class uses benecaster_email_headers to capture type, user, and show into a static property, then reads it back inside wp_mail_smtp_providers_mailer_get_body and clears it (one-shot) so subsequent emails start fresh.

Code

<?php
final class My_Addon_SendGrid_API_Categories {

    /** @var array<string, int|string>|null */
    private static ?array $pending_context = null;

    public static function register(): void {
        add_filter( 'benecaster_email_headers', [ self::class, 'capture_context' ], 10, 4 );
        add_filter( 'wp_mail_smtp_providers_mailer_get_body', [ self::class, 'inject_into_body' ], 10, 2 );
    }

    public static function capture_context( array $headers, string $type, int $user_id, int $show_id ): array {
        self::$pending_context = [
            'type'    => $type,
            'user_id' => $user_id,
            'show_id' => $show_id,
        ];
        return $headers;
    }

    public static function inject_into_body( array $body, string $mailer ): array {
        if ( 'sendgrid' !== $mailer || null === self::$pending_context ) {
            return $body;
        }

        $ctx                   = self::$pending_context;
        self::$pending_context = null;

        $body['categories'] = array_values( array_unique( array_merge(
            (array) ( $body['categories'] ?? [] ),
            [ 'benecaster', 'benecaster_' . $ctx['type'] ]
        ) ) );

        $body['custom_args'] = array_merge(
            (array) ( $body['custom_args'] ?? [] ),
            [
                'benecaster_type' => $ctx['type'],
                'user_id'         => (string) $ctx['user_id'],
                'show_id'         => (string) $ctx['show_id'],
            ]
        );

        return $body;
    }
}

add_action( 'init', [ My_Addon_SendGrid_API_Categories::class, 'register' ] );

View on GitHub →

Hooks Used

benecaster_email_headers