Skip to main content

​
Configuration

After installing the package, configure Lettermint Laravel to integrate with your application’s mail system.

​
Configuration file

The main configuration file is located at config/lettermint.php after publishing: 
return [
    // Lettermint API token
    'token' => env('LETTERMINT_TOKEN'),
    
    // Webhook configuration
    'webhooks' => [
        'secret' => env('LETTERMINT_WEBHOOK_SECRET'),
        'prefix' => env('LETTERMINT_WEBHOOK_PREFIX', 'lettermint'),
        'tolerance' => env('LETTERMINT_WEBHOOK_TOLERANCE', 300),
    ],
];

​
Environment variables

Add these variables to your .env file: 
# Required: Your Lettermint API token
LETTERMINT_TOKEN=your-lettermint-token

# Optional: Webhook configuration
LETTERMINT_WEBHOOK_SECRET=your-webhook-signing-secret
LETTERMINT_WEBHOOK_PREFIX=lettermint
LETTERMINT_WEBHOOK_TOLERANCE=300

# Optional: Route IDs for multiple mailers
LETTERMINT_ROUTE_ID=your-default-route-id
LETTERMINT_MARKETING_ROUTE_ID=your-marketing-route-id
LETTERMINT_TRANSACTIONAL_ROUTE_ID=your-transactional-route-id
Find your API token and webhook signing secret in your Lettermint project settings.

​
Mail configuration

​
Basic setup

Configure the Lettermint transport in your config/mail.php:
1

Add the Lettermint mailer

Add a new mailer configuration in the mailers array:
'mailers' => [
    'lettermint' => [
        'transport' => 'lettermint',
    ],
    
    // ... other mailers
],
2

Set as default (optional)

To use Lettermint as your default mailer, update the default setting:
'default' => env('MAIL_MAILER', 'lettermint'),
Or in your .env file:
MAIL_MAILER=lettermint

​
Using routes

Lettermint routes help you organize your email traffic. You can specify a route ID for each mailer: 
// config/mail.php
'mailers' => [
    'lettermint' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_ROUTE_ID'),
    ],
],
Then add the route ID to your .env: 
LETTERMINT_ROUTE_ID=your-route-id

​
Multiple mailers with different routes

Configure multiple mailers using the same Lettermint transport but with different route IDs: 
'mailers' => [
    'lettermint_marketing' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_MARKETING_ROUTE_ID'),
    ],
    'lettermint_transactional' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_TRANSACTIONAL_ROUTE_ID'),
    ],
],

​
Services configuration

Add the Lettermint service to your config/services.php: 
return [
    // ... other services
    
    'lettermint' => [
        'token' => env('LETTERMINT_TOKEN'),
    ],
];

​
Idempotency configuration

Idempotency prevents duplicate email sends, which is especially useful for queued jobs that might be retried.

​
Enable automatic idempotency

Configure idempotency settings in your config/mail.php mailer configuration: 
'mailers' => [
    'lettermint' => [
        'transport' => 'lettermint',
        'idempotency' => true, // Enable automatic content-based idempotency
        'idempotency_window' => 86400, // Window in seconds (default: 24 hours)
    ],
],

​
Configuration options

​
idempotency
boolean
default:"false"
Enable or disable automatic content-based idempotency
  • true: Generates idempotency keys based on email content
  • false: Disables automatic idempotency (user headers still work)
​
idempotency_window
integer
default:"86400"
Time window in seconds for deduplication
  • Default: 86400 (24 hours to match Lettermint API retention)
  • Set to match your needs (e.g., 3600 for 1 hour, 300 for 5 minutes)
  • When set to 86400 or higher, emails with identical content are permanently deduplicated within the API retention period

​
How automatic idempotency works

When idempotency is true, the driver generates a unique key based on:
  • Email subject, recipients (to, cc, bcc), and content
  • Sender address (to differentiate between different sending contexts)
  • Time window (if less than 24 hours)
This ensures:
  • Identical emails are only sent once within the configured time window
  • Retried queue jobs won’t create duplicate emails
  • Different emails or the same email after the time window will be sent normally

​
Per-mailer configuration

You can configure idempotency differently for each mailer: 
'mailers' => [
    'lettermint_marketing' => [
        'transport' => 'lettermint',
        'route_id' => 'marketing',
        'idempotency' => true, // Enable for marketing emails
        'idempotency_window' => 86400,
    ],
    'lettermint_transactional' => [
        'transport' => 'lettermint',
        'route_id' => 'transactional',
        'idempotency' => false, // Disable for transactional emails
    ],
],
The idempotency: false configuration only disables automatic idempotency. User-provided Idempotency-Key headers are always respected, giving you full control on a per-email basis.

​
Webhook configuration

Configure webhooks to receive email delivery events from Lettermint.

​
Webhook settings

The webhook configuration is in config/lettermint.php: 
'webhooks' => [
    // Webhook signing secret for verification
    'secret' => env('LETTERMINT_WEBHOOK_SECRET'),
    
    // Route prefix (results in /lettermint/webhook)
    'prefix' => env('LETTERMINT_WEBHOOK_PREFIX', 'lettermint'),
    
    // Timestamp tolerance in seconds (prevents replay attacks)
    'tolerance' => env('LETTERMINT_WEBHOOK_TOLERANCE', 300),
],

​
Environment variables

Add webhook settings to your .env file: 
# Required: Webhook signing secret
LETTERMINT_WEBHOOK_SECRET=your-webhook-signing-secret

# Optional: Customize webhook endpoint
LETTERMINT_WEBHOOK_PREFIX=lettermint
LETTERMINT_WEBHOOK_TOLERANCE=300

​
Webhook endpoint

The package automatically registers a webhook endpoint at: 
POST /{prefix}/webhook
By default, this is POST /lettermint/webhook. Configure this URL in your Lettermint dashboard.
Learn more about handling webhook events in the Webhooks guide.

​
Configuration options reference

​
Lettermint config (config/lettermint.php)

OptionTypeDefaultDescription
tokenstringnullYour Lettermint API token
webhooks.secretstringnullWebhook signing secret for verification
webhooks.prefixstringlettermintRoute prefix for webhook endpoint
webhooks.toleranceinteger300Timestamp tolerance in seconds

​
Mail config (config/mail.php)

OptionTypeDefaultDescription
transportstring-Must be lettermint
route_idstringnullLettermint route ID for this mailer
idempotencybooleanfalseEnable automatic content-based idempotency
idempotency_windowinteger86400Idempotency window in seconds

​
Next steps

Idempotency

Learn about automatic and custom idempotency keys

Webhooks

Handle email delivery events with typed Laravel events

Tags and metadata

Add tags and metadata for better tracking and analytics

Routes

Organize email traffic with Lettermint routes

Build docs developers (and LLMs) love

Get started for freeTalk to us