S/MIME Email signing

S/MIME - Secure/Multipurpose Internet Mail Extensions - is a standard for public key encryption and signing of Multipurpose Internet Mail Extensions - MIME - data. Mautic supports S/MIME Email signing to help verify the authenticity of your Emails and ensure that the Email content wasn’t modified in transit.

Note

S/MIME signing is currently only available when using the SMTP Email transport. It doesn’t work with API-based Email transports.

What’s S/MIME Email signing?

S/MIME Email signing adds a digital signature to your Emails, which allows recipients to:

Verify the sender’s identity - Confirm that the Email actually came from your organization
Ensure Email integrity - Verify that the Email content wasn’t tampered with during transmission
Build trust - Demonstrate to recipients that your organization follows Email security best practices

Note

This implementation focuses on signing Emails only. It doesn’t encrypt the Email body, which means the Email content is still readable to anyone who has access to it. Many Email clients don’t support S/MIME encryption, so signing provides verification without compatibility issues.

For more detailed information about S/MIME and why to use it, read this S/MIME: Secure e-mail encryption and signature article by mailbox.

How it works

When you turn on and properly configure S/MIME signing:

Mautic signs each outgoing Email with the private key for the sender’s Email address
Mautic attaches the signature to the Email as a smime.p7s file
Recipients with S/MIME-capable Email clients can verify the signature using the public certificate
If no certificate exists for a sender’s Email address, Mautic sends the Email unsigned without error

Turn on S/MIME signing

Turn on S/MIME signing through your Mautic configuration file. It isn’t available in the web interface.

Warning

Make sure you’re using the SMTP Email transport before turning on S/MIME signing. The feature doesn’t work with API-based Email transports.

Configuration

Add the following configuration parameters to your app/config/local.php file:

<?php
$parameters = array(
    // ... other configuration ...
    'smime_signing_enabled' => true,
    'smime_certificates_path' => '%kernel.project_dir%/var/smime_certificates',
);

Configuration parameters

smime_signing_enabled

set to true to turn on S/MIME Email signing or false to turn it off.

Default: false

smime_certificates_path

the absolute path to the directory where Mautic stores your S/MIME certificates. You can use %kernel.project_dir% to reference your Mautic installation directory.

Default: %kernel.project_dir%/var/smime_certificates

Generating S/MIME certificates

Each Email address that sends Emails from Mautic needs its own pair of certificates:

A public certificate - .crt file - that verifies your identity
A private key - .pem file - that signs the Emails

Self-signed certificates

For testing purposes, you can create self-signed certificates. However, for production use, you should obtain certificates from a trusted Certificate Authority.

To create a self-signed certificate and private key:

# Create a private key and certificate signing request
openssl req -newkey rsa:4096 -nodes -keyout sender@example.com.pem -out sender@example.com.csr

# Create a self-signed certificate valid for 1 year
openssl x509 -req -days 365 -in sender@example.com.csr -signkey sender@example.com.pem -out sender@example.com.crt

Important

Replace sender@example.com with the actual Email address you’re using to send Emails from Mautic.

Production certificates

For production use, obtain S/MIME certificates from a trusted Certificate Authority - CA. Many Certificate Authorities offer S/MIME certificates, and the process typically involves:

Generating a Certificate Signing Request - CSR
Submitting the CSR to the CA along with identity verification documents
Receiving the signed certificate from the CA

To see an example of how this process works in practice, refer to the Instructions for obtaining a personal S/MIME certificate by creating a CSR article by Mozilla.

Installing certificates

Certificate file naming

Name certificates according to the Email address they’re for:

Public certificate: email@example.com.crt
Private key: email@example.com.pem - plain text - or email@example.com.pem.enc - encrypted

Replace email@example.com with the actual sender Email address.

Important

The Email address in the filename must exactly match the From address used when sending Emails.

Certificate directory structure

Place your certificate files in the directory specified by smime_certificates_path:

/var/smime_certificates/
├── admin@example.com.crt
├── admin@example.com.pem
├── support@example.com.crt
└── support@example.com.pem

Setting permissions

Ensure that the web server User has read access to the certificate directory and files:

# Set ownership (replace www-data with your web server user)
chown -R www-data:www-data /path/to/mautic/var/smime_certificates

# Set directory permissions
chmod 755 /path/to/mautic/var/smime_certificates

# Set certificate permissions
chmod 644 /path/to/mautic/var/smime_certificates/*.crt
chmod 600 /path/to/mautic/var/smime_certificates/*.pem

Warning

Private keys - .pem files - should have restrictive permissions - 600 - to prevent unauthorized access.

Encrypting private keys

To enhance security, you can encrypt your private keys using Mautic’s encryption system. Mautic stores the encrypted private keys with the .pem.enc extension.

Benefits of encryption

Encrypting private keys adds an extra layer of security:

If someone compromises your server, they can’t use the encrypted keys without Mautic’s secret key
The encryption uses your Mautic instance’s secret_key from the configuration
Mautic automatically decrypts the keys when needed to sign Emails

Important

Make sure you have a secret_key configured in your app/config/local.php file. Mautic creates this automatically during installation.

Creating encrypted keys

To encrypt an existing private key:

Ensure your secret_key configures in app/config/local.php
Use Mautic’s encryption helper or the command line:

# Using PHP to encrypt the key
php -r "
require 'app/config/local.php';
require 'app/bundles/CoreBundle/Helper/EncryptionHelper.php';
\$helper = new \Mautic\CoreBundle\Helper\EncryptionHelper(
    new \Mautic\CoreBundle\Helper\CoreParametersHelper(new \Symfony\Component\DependencyInjection\ParameterBag\ParameterBag(\$parameters))
);
\$key = file_get_contents('var/smime_certificates/sender@example.com.pem');
file_put_contents('var/smime_certificates/sender@example.com.pem.enc', \$helper->encrypt(\$key));
"

After creating the encrypted version, you can remove the plain text .pem file for security
Mautic automatically uses the encrypted version - .pem.enc - if it exists

Key priority

When looking for a private key, Mautic checks in this order:

Encrypted key: email@example.com.pem.enc
Plain text key: email@example.com.pem

If both exist, the encrypted version takes priority.

Testing S/MIME signing

After configuring S/MIME signing:

Send a test Email from Mautic using an Email address that has certificates configured
Select the Email source/headers in your Email client
Look for these indicators that Mautic signed the Email:
- Content-Type header contains multipart/signed
- An attachment named smime.p7s
- protocol application/x-pkcs7-signature
If your Email client supports S/MIME, you should see a verification indicator - such as a seal or checkmark

Troubleshooting S/MIME

Emails aren’t signed

If Mautic doesn’t sign Emails, select:

S/MIME enabled - verify smime_signing_enabled sets to true in local.php
Using SMTP transport - S/MIME only works with SMTP. Select your Email transport settings
Certificates exist - confirm the .crt and .pem files exist in the certificates directory
Correct filenames - certificate filenames must exactly match the sender Email address
File permissions - the web server User must have read access to the certificate files
Select logs - look in var/logs/mautic_prod.log for any S/MIME-related errors

Certificates not found errors

If you see certificate errors in the logs:

Verify the smime_certificates_path specifies correctly in your configuration
Ensure that Mautic names certificate files correctly - email@example.com.crt and .pem
Ensure the Email address in the filename exactly matches the From address
Verify file permissions allow the web server User to read the files

Certificate validation errors

If recipients Reports certificate validation errors:

Self-signed certificates - these aren’t trusted by default. Recipients need to manually trust them
Expired certificates - select your certificate expiration dates
Certificate chain - ensure you’re using the full certificate chain from your Certificate Authority
Domain mismatch - the certificate’s Email address must match the From address

Performance considerations

S/MIME signing adds a small amount of processing overhead to each Email:

Mautic performs signing for each Email individually
When you turn on S/MIME, Mautic turns off batch Email processing - token-based sending - to ensure proper signing
For high-volume Email sending, monitor your server resources

Limitations

Current limitations of S/MIME signing in Mautic:

SMTP only - S/MIME signing only works with the SMTP Email transport. API-based transports aren’t supported.
Signing only - this implementation signs Emails but doesn’t encrypt the Email body. The content is still readable.
No batch processing - when you turn on S/MIME, Mautic turns off batch Email processing - token-based sending - to ensure proper signing.
One Email per request - Mautic sends each Email individually rather than in batches.

Note

If you turn on S/MIME signing and you’re using a non-SMTP transport, Mautic forces sending one Email per request, but signing may not work correctly. Always use SMTP for S/MIME signing.

Additional resources

For more information about S/MIME:

S/MIME Email signing

What’s S/MIME Email signing?

How it works

Turn on S/MIME signing

Configuration

Configuration parameters

Generating S/MIME certificates

Self-signed certificates

Production certificates

Installing certificates

Certificate file naming

Certificate directory structure

Setting permissions

Encrypting private keys

Benefits of encryption

Creating encrypted keys

Key priority

Testing S/MIME signing

Troubleshooting S/MIME

Emails aren’t signed

Certificates not found errors

Certificate validation errors

Performance considerations

Limitations

Additional resources

Related documentation