Skip to main content
Skip table of contents

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:

  1. the default configuration set at the Transactional Email Technical Account with which your source Application is authenticated to;

  2. use the signing flag into the JobRequest you sent to that Technical Account, working with REST APIs or SMTP Header;

  3. the S/MIME certificate uploaded into the Message Signing PKI (Public Key Infrastructure), you have 2 options:

    1. using our User Synchronisation Encryption (USE) tool and uploading your certificate by yourself;

    2. 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:

CODE
{ 
  "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:

  1. Sent a JobRequest with an EnvelopeFrom matching a S/MIME certificate uploaded into the PKI

  2. AND

    1. Set explicitly the signing flag to active: true into that JobRequest

    2. OR set the default Technical Account configuration to defaultActive: true

All potential scenarios

JobRequest signing flag

(REST or SMTP)

Technical Account configuration

Public Key Infrastructure

Result

empty

defaultActive: true

EnvelopeFrom matching a S/MIME certificate

Email is signed and sent

active: true

defaultActive: true

EnvelopeFrom matching a S/MIME certificate

Email is signed and sent

active: false

defaultActive: true

EnvelopeFrom matching a S/MIME certificate

Email sent and not signed

empty

defaultActive: false

EnvelopeFrom matching a S/MIME certificate

Email sent and not signed

active: true

defaultActive: false

EnvelopeFrom matching a S/MIME certificate

Email is signed and sent

active: false

defaultActive: false

EnvelopeFrom matching a S/MIME certificate

Email sent and not signed

empty

defaultActive: true

EnvelopeFrom not matching a S/MIME certificate

PROCESSING_FAILED

active: true

defaultActive: true

EnvelopeFrom not matching a S/MIME certificate

PROCESSING_FAILED

active: false

defaultActive: true

EnvelopeFrom not matching a S/MIME certificate

PROCESSING_FAILED

empty

defaultActive: false

EnvelopeFrom not matching a S/MIME certificate

PROCESSING_FAILED

active: true

defaultActive: false

EnvelopeFrom not matching a S/MIME certificate

PROCESSING_FAILED

active: false

defaultActive: false

EnvelopeFrom not matching a S/MIME certificate

PROCESSING_FAILED

Tracking Points for administrators

myEAS Live Search

Email successfully signed

2024-09-25 16_17_32-PowerPoint Slide Show  -  WIP TEM Message Signing - Sales enablement V4.pptx.png

Push Notification samples

SMIME_SIGNING (intermediate)

Phase:             PROCESS
Type:               SMIME_SIGNING
State:               INTERMEDIATE
Subtype:          OK

JSON
{
  "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

JSON
{
  "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"
},
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.