Message Signing setup and usage
Setup overview
Step | Description |
---|---|
Step 1: book the Message Signing feature | Contact your main Sale contact to order the Message Signing add-on and update your Transactional Email contract. |
Step 2: feature configuration at the Account level | Get in touch with our Implementation Team to configure the Message Signing feature. Choose for which Account(s) you want to enable this feature and define the default expected behaviour. |
Step 3: get a paid S/MIME certificate | You can buy a S/MIME certificate from any Certificate Authority of your choice. Note: Retarus has a preferred partnership with Swiss Sign to not only help you ordering a paid certificate but also automatically upload it into our built-in Public Key Infrastructure (PKI), see step 4. |
Step 4: upload your S/MIME cetificate(s) | During the Implementation phase of the Message Signing feature, or by opening a Service Request, you can provide us your existing S/MIME certificate(s) to be uploaded into the built-in Public Key Infrastructure (PKI). Note: you can upload and manage your certificates by yourself using our User Synchronisation Encryption (USE) tool. Please contact our Support Team to request the set up of this tool. |
Step 5: connect your source Applications to the Technical Account | As now the Message Signing feature is fully configured, you can now connect all your source Applications to the Technical Account for which the feature has been enabled. See “Account authentication” section. |
How to use the Message Signing feature
There are 3 complementary layers to control the Message Signing feature:
the default configuration set at the Transactional Email Technical Account with which your source Application is authenticated to;
use the signing flag into the JobRequest you sent to that Technical Account, working with REST APIs or SMTP Header;
the S/MIME certificate uploaded into the Message Signing PKI (Public Key Infrastructure), you have 2 options:
using our User Synchronisation Encryption (USE) tool and uploading your certificate by yourself;
or contact our Support Team to request your S/MIME certificate to be uploaded by us.
Technical Account configuration
First of all, the Message Signing feature must have been booked, enabled and configured at the Technical Account level by our Implementation team. Thus to allow JobRequest to use this feature. 2 parameters must be set:
active
: define if the feature is authorized to be used with the Technical Account or not, means that if the Technical Account allows to route the JobRequest to the built-in signing component;defaultActive
: define the default behaviour expected if nothing is explictly set into the JobRequest sent to the Technical Account (see the paragraph below).
Please review all the potential configuration scenarios and related results later below.
It is recommended to implement one dedicated Technical Account for all your business applications requiring the sent signed emails and force the signing mechanism for all JobRequests sent to this Technical Account. To do so, ask to set the defaultActive
parameter to true
, therefore you don’t even need to explictly set the signing flag into any JobRequest.
JobRequest
Just as the vast majority of Transactional Email features, Message Signing can be controled at the JobRequest level. Thus to provide you sufficient flexibility to choose which email must be sent out signed or not.
If the signing flag is explicitly defined at the JobRequest level (true
or false
), it overwrittes the Technical Account defaultActive
configuration.
REST APIs
With Message Signing you have the possibility to flag which email within a REST JobRequest should sent out signed using your S/MIME certificate, example:
{
"mail": ...
"job": {
...
"features": {
"messageSigning": {
"active": true
}
}
}
}
Find more information about this Message Signing REST parameter here or on the Transactional Email API developer portal.
SMTP Adapter
With Message Signing you have the possibility to flag which email within a SMTP JobRequest should sent out signed using your S/MIME certificate, example:
X-RETARUS-M4A-MESSAGE-SIGNING-ACTIVE: true
Find more information about this Message Signing SMTP Header here.
Public Key Infrastructure
Each S/MIME certificate that have been imported into the Message Signing PKI (Public Key Infrastructure) is related to one specific sender address:
to sign an email the EnvelopeFrom address set into the JobRequest must match at least one S/MIME signing key uploaded into the Message Signing PKI;
If a JobRequest asks to digitally sign an email with a sender address not matching a S/MIME certificate uploaded into the PKI, the JobRequest will be considered as “PROCESSING_FAILED”.
Several S/MIME certificates can be uploaded into the Message Signing PKI. The sender address set into these certifcates is the key identifier to know which signing key to apply to the JobRequest.
Wrap up
To trigger the Message Signing feature and send signed emails you must:
Sent a JobRequest with an EnvelopeFrom matching a S/MIME certificate uploaded into the PKI
AND
Set explicitly the signing flag to
active: true
into that JobRequestOR set the default Technical Account configuration to
defaultActive: true
Tracking Points for administrators
myEAS Live Search
Email successfully signed

Push Notification samples
SMIME_SIGNING (intermediate)
Phase: PROCESS
Type: SMIME_SIGNING
State: INTERMEDIATE
Subtype: OK
{
"meta":{
"event": {
"description": "The mail was signed successfully.",
"phase": "PROCESS",
"state": "INTERMEDIATE",
"subType": "OK",
"ts": "2024-11-08T07:38:42.224Z",
"type": "SMIME_SIGNING"
},
SMIME_SIGNING FAILED
Phase: PROCESS
Type: DROPPED
State: FINISHED
Subtype: PROCESSING_FAILED
{
"meta":{
"event": {
"description": "signature with given key identifier (sender.address@your-domain) failed",
"phase": "PROCESS",
"state": "FINISHED",
"subType": "PROCESSING_FAILED",
"ts": "2024-11-12T08:46:45.680Z",
"type": "DROPPED"
},