README

Add DKIM signatures to the mails of your Laravel app, without replacing the mailer. One domain or many, with commands to create the key and to check the DNS record.

One domain:

MAIL_DKIM_ENABLED=true
MAIL_DKIM_DOMAIN=example.com
MAIL_DKIM_SELECTOR=default

Several domains, in config/laravel-dkim.php:

'sender' => [
    'default' => ['dkim_selector' => 'default', 'dkim_domain' => 'example.com'],
    'shop'    => ['dkim_selector' => 'shop', 'dkim_domain' => 'shop-example.org'],
],

Mails from info@example.com are signed with d=example.com, mails from orders@shop-example.org with d=shop-example.org.

Contents

• What it does
• When you do not need it
• Requirements
• Installation
• Quickstart
• How it works
• Configuration
• Multiple domains
• Fallback and error handling
• Commands
• Keys and security
• Troubleshooting

What it does

The package listens to Laravel's Illuminate\Mail\Events\MessageSending event and adds a DKIM-Signature header (RFC 6376, rsa-sha256) to every outgoing mail. It does not replace the mailer or the mail service provider, so your mailers, transports and other mail packages keep working. Each mail is signed with the sender that matches its From address, so one app can sign mails for several domains. php artisan dkim:generate creates the key and shows the DNS record, php artisan dkim:check checks the config, the keys and the DNS records.

When you do not need it

If your mail server or mail provider already signs your mails with DKIM for your domain, you do not need this package. A second signature for the same domain adds nothing. The package helps when you send through an SMTP server that does not sign your mails.

To find out, send a mail to an address you can read and look at the headers: a DKIM-Signature header with d= set to your domain means the mail is already signed.

Requirements

• PHP 8.3 or higher
• Laravel 12 or 13
• PHP extension openssl

Use version 3.x for older PHP or Laravel versions (no longer maintained).

Upgrading from 3.x? Please read the upgrade guide, or let your AI agent do the upgrade.

Installation

composer require tobymaxham/laravel-dkim

The service provider is registered automatically.

To change the config (e.g. for multiple domains), publish it:

php artisan vendor:publish --tag=laravel-dkim-config

Quickstart

1. Create a key for the domain of your From address:

php artisan dkim:generate example.com

The private key is stored in storage/app/dkim/example.com.default.pem. The command shows the DNS record and the values for your .env.

2. Add the DNS record at your DNS provider, as shown by the command:

3. Enable signing in your .env:

MAIL_DKIM_ENABLED=true
MAIL_DKIM_DOMAIN=example.com
MAIL_DKIM_SELECTOR=default

4. Check the key and the DNS record (DNS changes can take a while):

php artisan dkim:check

How it works

• When Laravel sends a mail, it fires MessageSending. The listener TobyMaxham\LaravelDkimSigner\Listener\ApplyDkimSignature picks the sender for the From address and adds the signature to the message. Then Laravel hands the message to the transport.
• Queued mails are signed when they are sent, so in the queue worker. The worker needs access to the private key.
• The signature covers the body and the headers, including Date and Message-ID. If the message has no Date or Message-ID yet, they are created when it is signed and added to the message, so they do not change on send. Bcc is never signed and the mail still reaches all Bcc recipients.
• Changes to the message after signing (e.g. by another MessageSending listener that runs later) make the signature invalid.
• A mail that already has a signature with the same domain and selector is not signed again.

The test suite verifies the signatures of the sent mails with the public key (plain text, HTML with attachment, both canonicalizations).

Configuration

The config file config/laravel-dkim.php explains every option. Global options:

Options per sender (in sender.<name>; the env variables are used by the default sender):

The config is validated when a mail is signed. Invalid values throw an InvalidDkimConfiguration exception that names the config key, e.g. Invalid DKIM configuration [laravel-dkim.sender.default.dkim_selector]: .... The message never contains the key or the passphrase.

Multiple domains

Each mail is signed by one sender. The sender is chosen by the first From address of the mail, in this order:

1. Address: the sender that lists the From address in addresses.
2. Domain: the sender whose dkim_domain is the domain of the From address or a parent domain of it, e.g. example.com for info@mail.example.com. If several match, the longest dkim_domain wins; for the same dkim_domain the first sender in the config wins.
3. Any domain: the sender without dkim_domain. It signs with the domain of the From address. Only one sender may have no dkim_domain.
4. Fallback: otherwise dkim_fallback decides.

Upper and lower case do not matter. The name of a sender is only a name, it is not compared with the From address.

'sender' => [
    'default' => [
        'dkim_selector' => env('MAIL_DKIM_SELECTOR', 'default'),
        'dkim_domain'   => env('MAIL_DKIM_DOMAIN'), // example.com
    ],

    'shop' => [
        'dkim_selector'    => 'shop',
        'dkim_domain'      => 'shop-example.org',
        'dkim_private_key' => env('MAIL_DKIM_SHOP_KEY'),
    ],

    'newsletter' => [
        'dkim_selector' => 'news',
        'dkim_domain'   => 'example.com',
        'addresses'     => ['news@example.com'],
    ],
],

Create a key and a DNS record for each sender:

php artisan dkim:generate shop-example.org --selector=shop
php artisan dkim:generate example.com --selector=news

Senders without dkim_private_key use storage/app/dkim/{domain}.{selector}.pem, the path dkim:generate writes to.

Fallback and error handling

dkim_fallback (MAIL_DKIM_FALLBACK) decides about mails whose From address matches no sender (and mails without From address):

dkim_on_error (MAIL_DKIM_ON_ERROR) decides what happens when a mail can not be signed, e.g. because of an invalid config, a missing key, a wrong passphrase or dkim_fallback=fail:

All exceptions extend TobyMaxham\LaravelDkimSigner\Exceptions\DkimException (a RuntimeException). An invalid value of dkim_on_error itself always throws.

Commands

dkim:generate

php artisan dkim:generate {domain?} {--selector=} {--bits=2048} {--path=} {--passphrase} {--force}

Creates an RSA key pair. Without a domain or selector it uses dkim_domain and dkim_selector of the default sender.

• The private key is written to --path or storage/app/dkim/{domain}.{selector}.pem with mode 0600 (a new directory gets 0700). It is never printed.
• An existing file is never overwritten without --force.
• --passphrase asks for a passphrase and encrypts the key (AES-256).
• --bits accepts 1024 to 4096. Keys below 2048 bits print a warning.
• A path in the public directory prints a warning.

   INFO  Private key written to storage/app/dkim/example.com.default.pem (mode 0600). Never commit it.

Add this TXT record to the DNS of example.com:

  Name:  default._domainkey.example.com
  Value: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxPwEXnYWdTjjNTf4gYtRXoB8...

If your DNS provider only accepts strings up to 255 characters, enter the value as these strings:

  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxPwEXnYW..." "ZTkLAmLYdyoqDotzCJ57..."

Add these values to your .env:

  MAIL_DKIM_ENABLED=true
  MAIL_DKIM_DOMAIN=example.com
  MAIL_DKIM_SELECTOR=default

Run "php artisan dkim:check" when the DNS record is published.

dkim:check

php artisan dkim:check {sender?} {--domain=} {--no-dns}

Checks all senders (or the given one): the config, the private key and the passphrase, and whether the TXT record {selector}._domainkey.{domain} contains the public key of the private key.

+-----------+------------------+----------+-------------+-----------------------------------------------------------------------+
| Sender    | Domain           | Selector | Status      | Details                                                               |
+-----------+------------------+----------+-------------+-----------------------------------------------------------------------+
| default   | example.com      | default  | OK          | Key is valid and matches the DNS record at default._domainkey.exam... |
| shop      | shop-example.org | shop     | DNS_MISSING | No TXT record found at shop._domainkey.shop-example.org.              |
+-----------+------------------+----------+-------------+-----------------------------------------------------------------------+

The exit code is 1 if a sender has another status than OK or SKIPPED, or if a global option is invalid. Use it in your deployment. --no-dns only checks the config and the keys. For the sender without dkim_domain, --domain=example.com checks the key and record of that domain.

Keys and security

• Never commit the private key and never store it in the public directory. The default path storage/app/dkim is outside public, and in a new Laravel 12 or 13 app storage/app/.gitignore already ignores it. Check this in your app.
• Keep the key file readable only for the user that sends the mails (dkim:generate uses mode 0600). Remember the queue workers and every server that sends mails.
• dkim_private_key accepts a file path or the PEM string itself (starting with -----BEGIN), e.g. from a secret store. A file is easier to handle than a PEM string in .env.
• Use a passphrase (--passphrase, MAIL_DKIM_PASSPHRASE) if the key file may be copied, e.g. in backups.
• Rotate keys with a new selector: create a key with a new selector (dkim:generate example.com --selector=2026-11), publish its DNS record, check it with dkim:check, then change MAIL_DKIM_SELECTOR. Remove the old DNS record a few days later, when no mails signed with the old key are on their way any more.

Without the command, you can create a key with OpenSSL:

openssl genrsa -out example.com.default.pem 2048
openssl rsa -in example.com.default.pem -pubout -outform der | openssl base64 -A

The second command prints the value for p= in the DNS record v=DKIM1; k=rsa; p=....

Troubleshooting

Testing

composer test
composer test-coverage
composer analyse

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please see the security policy on how to report a vulnerability. Do not use the issue tracker.

Support me

Credits

• TobyMaxham
• Florian Jahn (the idea for the default domain and key path, #1)
• All Contributors

License

The MIT License (MIT). Please see License File for more information.