S/MIME Emails

An S/MIME Emails rule signs and encrypts email your users send, and decrypts and validates signed or encrypted email they receive, using certificates you upload to mxHERO. Users don't need certificates in their own mail apps. This page explains what each action does, how to set up certificates and rules, and what happens when a certificate is missing.

Before you begin

• Your mail is routed through mxHERO in the directions you want to protect: outbound for signing and encryption, inbound for decryption and validation. See Routing Architectures.
• You have the certificates:
  • for your own users: .p12 files (with the private key) and their passwords;
  • for external partners you encrypt to: their public certificates as .pem files.
• Turn off TNEF (winmail.dat) in Exchange or Microsoft 365. S/MIME rules skip TNEF messages. See Preventing TNEF Encapsulation.

What each action does

mxHERO always runs the actions in this order: Decrypt, Validate, Sign, Encrypt.

• Decrypt and Validate run for the recipient's organization. For incoming mail, they run before your other rules, so rules such as Protect Attachments see the decrypted content.
• Sign and Encrypt run for the sender's organization, after your other rules have changed the message, so the signature covers the final content.

An S/MIME rule only does what its certificates allow. If a certificate is missing, that action is skipped without an error for that message.

Warning: If the recipient has no primary certificate in mxHERO, an Encrypt rule skips encryption and the email is delivered unencrypted. If the S/MIME service fails, the email is also delivered as is. If unencrypted delivery isn't acceptable for some recipients, make sure every one of them has a certificate, and monitor Reports › Notifications for smime_error.

Set up certificates

Certificates and the addresses they belong to are managed in Settings › S/MIME Certificates, which has two tabs: Certificates and Accounts. You can also do this in bulk with the S/MIME API.

Upload a certificate

1. Open Settings › S/MIME Certificates.

2. On the Certificates tab, click Add certificate.

   

3. Click Add certificate file... and choose the file. Only .pem and .p12 files are accepted.

4. Enter a name (required) and, optionally, a description.

5. For a .p12 file, enter its password.

6. Save.

mxHERO checks the password, then protects the private key with an organization-specific password. Your original password is not stored. The certificate appears in the list with its status (active or expired) and upload date. Open it to see its subject, issuer, serial number, validity period, email addresses and what it can do (sign, encrypt, decrypt, verify).

If your files have other extensions:

• A .pfx file is the same format as .p12. Rename it to .p12.
• A .crt or .cer file in text (Base64) form can be renamed to .pem. A binary (DER) one must be converted first, for example: openssl x509 -inform der -in partner.cer -out partner.pem

Link certificates to email addresses

A certificate is used only once it's linked to an email address on the Accounts tab. These S/MIME accounts are separate from the accounts in Settings › Accounts and Groups.

1. On the Accounts tab, click Add account.

   

2. Enter the Email address, for example jordan@example.com or a partner's buyer@partner.example.

3. Click + Link certificate, then choose the certificate in Search certificates by name.

4. Select Primary for the certificate in current use. Only one certificate can be primary.

5. To keep older certificates (after a renewal), click + Add certificate and link them too, without Primary.

6. Click Save.

How mxHERO uses an account's certificates:

• The Primary certificate signs the user's outgoing email (must be a .p12), and is the certificate other senders encrypt to.
• All linked certificates are tried when decrypting, so keep expired ones linked as long as users may receive email encrypted for them.
• Only addresses in your organization's domains can sign. External addresses are used for encryption and validation.

To delete a certificate, first remove it from every account that uses it. The error message lists those accounts.

Create an S/MIME Emails rule

Usually you create two rules: one for outgoing mail (Sign, Encrypt) and one for incoming mail (Decrypt, Validate). You can also use one rule with Between and all four actions.

Step 1: Action

1. Open Rules › Create a Rule, click S/MIME Emails, then Start Rule Creation.

2. Select one or more actions: Validate (selected by default), Sign, Encrypt, Decrypt. The Summary lists them under S/MIME Actions.

   

3. Optionally, with Validate selected, open Advanced Options and turn on Add invalid S/MIME subject ("Include a custom subject to be included when S/MIME validation fails"). Enter the Failed validation subject, for example [SMIME INVALID] (up to 100 characters). The field can't be empty while the option is on.

   

4. Click Confirm.

There are no attachment filters, storage steps or extra actions for S/MIME rules.

Step 2: Target

1. Under Rule Scope:, Email Flow is the only choice.

2. Under Target all emails sent:, choose Between or From, then the Sender and Recipient.

   Goal	Direction, Sender, Recipient	Actions
   Sign everything your users send	From, Organization, Anyone	Sign
   Encrypt email to a partner	From, Organization, partner.example	Encrypt (or Sign + Encrypt)
   Check signatures on incoming email	From, Anyone, Organization	Validate (+ Decrypt)
   Full S/MIME with one partner	Between, Organization, partner.example	Sign, Encrypt, Decrypt, Validate

3. Optionally open Advanced Options: Include From, To and CC when evaluating which emails will be processed. or Include From header when evaluating which emails will be processed. (both off by default).

4. Click Confirm.

5. Optionally click Add Filters for Use filter policy or Sender/Recipient (From/To) Exclusions. See Filters and Exclusions.

If several S/MIME rules match the same message, only one applies for each direction: the first in the fixed order, which favors the rule with the most specific sender and recipient. Put all the actions a flow needs in one rule rather than spreading them over overlapping rules.

Name and save

Enter a Rule Name, optionally a Rule Description, and click Save Rule. The rule applies within one to two minutes.

Verify

1. Upload a .p12 for a pilot user and set it as Primary.
2. Create a Sign rule from that user to Anyone. Send an email to an external mailbox you control. Your mail app should show the message as signed by the pilot user's certificate.
3. For encryption, upload a test recipient's .pem, link it as Primary for that address, add Encrypt, and send again. The recipient's mail app should show the message as encrypted.
4. In Reports › Email Flow Logs, open the message. The S/MIME event shows the result of each action and the certificates used. If no action could run, the log shows "No S/MIME certifies managed by organization". See Email Flow Logs.

Limits and failure behavior

• Email Flow only. Email already in mailboxes isn't processed.
• Upload formats: .pem and .p12 only.
• TNEF (winmail.dat) messages are skipped and delivered as is.
• A missing certificate skips that action silently. A processing failure is retried when temporary; otherwise the email is delivered without that S/MIME step and smime_error is recorded in Reports › Notifications.
• Validation never blocks delivery. It can only add the subject prefix.
• A system that changes messages after they are signed (for example, one that adds a disclaimer after mxHERO) breaks the signature.

Troubleshooting

Related pages

• S/MIME Validation Failures
• S/MIME API
• Create a Rule
• How Rules Work
• Notification Error Codes