Skip to main content
The Lettermint Laravel driver supports adding tags and metadata to your emails for better organization, tracking, and analytics in the Lettermint dashboard.

​
Tags

Tags help you categorize and filter your emails in the Lettermint dashboard. You can add one tag per email. 
use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

Mail::send((new WelcomeEmail($user))
    ->tag('onboarding')
);

​
Method 2: Using the envelope method in your Mailable

use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Mail\Mailable;

class WelcomeEmail extends Mailable
{
    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Welcome to our platform!',
            tags: ['onboarding'], // Only one tag is allowed
        );
    }
}

​
Method 3: Using custom header (backward compatibility)

The Lettermint Laravel driver also supports the X-LM-Tag header for backward compatibility: 
use Illuminate\Mail\Mailables\Headers;
use Illuminate\Mail\Mailable;

class WelcomeEmail extends Mailable
{
    public function headers(): Headers
    {
        return new Headers(
            text: [
                'X-LM-Tag' => 'onboarding',
            ],
        );
    }
}
When both TagHeader and X-LM-Tag are present, the TagHeader takes precedence.

​
Metadata

Metadata allows you to attach custom key-value pairs to your emails for enhanced tracking and analytics. 
use App\Mail\OrderConfirmation;
use Illuminate\Support\Facades\Mail;

Mail::send((new OrderConfirmation($order))
    ->metadata('order_id', $order->id)
    ->metadata('customer_id', $order->customer_id)
);

​
Method 2: Using the envelope method

use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Mail\Mailable;

class OrderConfirmation extends Mailable
{
    public function __construct(
        public Order $order
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Order Confirmation',
            metadata: [
                'order_id' => $this->order->id,
                'customer_id' => $this->order->customer_id,
                'order_total' => $this->order->total,
            ],
        );
    }
}

​
Combining tags and metadata

You can use both tags and metadata together for comprehensive email tracking: 
use Illuminate\Support\Facades\Mail;
use App\Mail\OrderShipped;

Mail::send((new OrderShipped($order))
    ->tag('transactional')
    ->metadata('order_id', $order->id)
    ->metadata('tracking_number', $order->tracking_number)
);

​
Common use cases

​
User tracking

Track which users receive which emails: 
Mail::send((new WelcomeEmail($user))
    ->tag('onboarding')
    ->metadata('user_id', $user->id)
    ->metadata('signup_source', $user->signup_source)
);

​
Campaign tracking

Track email campaigns: 
Mail::send((new NewsletterEmail($campaign))
    ->tag('newsletter')
    ->metadata('campaign_id', $campaign->id)
    ->metadata('campaign_name', $campaign->name)
    ->metadata('sent_at', now()->toIso8601String())
);

​
Order tracking

Track order-related emails: 
Mail::send((new OrderConfirmation($order))
    ->tag('transactional')
    ->metadata('order_id', $order->id)
    ->metadata('order_total', $order->total)
    ->metadata('payment_method', $order->payment_method)
);

​
User behavior tracking

Track emails related to specific user actions: 
Mail::send((new PasswordResetEmail($user))
    ->tag('user-notification')
    ->metadata('user_id', $user->id)
    ->metadata('notification_type', 'password_reset')
    ->metadata('ip_address', request()->ip())
);

​
Analyzing emails in the dashboard

Tags and metadata appear in the Lettermint dashboard, allowing you to:
  • Filter emails by tag
  • Search emails by metadata values
  • Generate analytics reports based on tags and metadata
  • Track email performance by category

​
Tag and metadata best practices

1

Use consistent naming

Use consistent tag names across your application. Consider creating constants:
class EmailTag {
    const TRANSACTIONAL = 'transactional';
    const MARKETING = 'marketing';
    const NOTIFICATION = 'notification';
}

Mail::send((new WelcomeEmail($user))->tag(EmailTag::TRANSACTIONAL));
2

Document metadata keys

Document the metadata keys you use for easier tracking:
// Common metadata keys:
// - user_id: The ID of the user receiving the email
// - order_id: Related order ID for transactional emails
// - campaign_id: Marketing campaign identifier
3

Keep metadata relevant

Only include metadata that’s useful for tracking and analytics. Don’t include sensitive information.
4

Use meaningful values

Use clear, meaningful values that make sense when viewing in the dashboard:
// Good
->metadata('email_type', 'password_reset')

// Less clear
->metadata('type', 'pr')

​
Testing tags and metadata

You can test that tags and metadata are properly set: 
use Tests\TestCase;
use Symfony\Component\Mailer\Header\TagHeader;
use Symfony\Component\Mailer\Header\MetadataHeader;

class EmailTagsTest extends TestCase
{
    public function test_email_has_correct_tag()
    {
        $email = new WelcomeEmail($user);
        $envelope = $email->envelope();
        
        $this->assertEquals(['onboarding'], $envelope->tags);
    }
    
    public function test_email_has_correct_metadata()
    {
        $order = Order::factory()->create(['id' => 123]);
        $email = new OrderConfirmation($order);
        $envelope = $email->envelope();
        
        $this->assertArrayHasKey('order_id', $envelope->metadata);
        $this->assertEquals(123, $envelope->metadata['order_id']);
    }
}

​
Compatibility notes

The driver supports Laravel’s native tag() and metadata() methods (Laravel 9+).
The X-LM-Tag header is supported for backward compatibility and to minimize confusion with the way of tagging emails sent via the SMTP relay.

Build docs developers (and LLMs) love

Get started for freeTalk to us