Skip to main content

Registered Mail Service

The Registered Mail service can be used in order to send registered documents to enterprises and citizens. Upon publication the service will provide a signature containing the necessary information to prove that the message has been sent to the recepient.

WARNING :

The Registered Mail service is only available to Social Security Institutions

Publications happen through the POST /registeredMails method of the Registered Mail RESTful API. This method uses a multipart HTTP POST to send one or several documents attached to a registered message. The API fully supports end to end streaming.

The authentication has to be done via an OAuth2 token request. See the onboarding process to configure your enterprise as a new OAuth client. This needs to be done in order to have an OAuth client ID and configurations of senderApplicationId & messageTypeId that are needed during the publication of a registered message.

After the onboarding a token needs to be retrieved in order to call the Registered Mail Service. More information on how to retrieve a token can be found on the Becoming a Document Sender page. The necessary scope however differs from the standard Document Sender implementation. In order to call the Registered Mail Service the scope scope:ksz-bcss:registered:epost-rest:registeredmailsender is needed.

Endpoints​

Once you have got your token, you can call a method using one of these endpoints:

EnvironmentEndpoint e-Box enterprise
Acceptancehttps://services-acpt.socialsecurity.be/REST/registeredMail/v1
Productionhttps://services.socialsecurity.be/REST/registeredMail/v1

Minimum publication example of a registered mail​

registeredMailToPublish: This part contains the meta information of the message.

Example:

registeredMailToPublish: {
  "recipient": {
    "eboxType": "enterprise",
    "ssin": "0123456789"
  },
  "subject": {
    "nl": "Registered mail example title"
  },
  "messageTypeId": "messageTypeIdentifier",
  "senderApplicationId": "applicationIdentifier",
  "customerReference": "identifierDefinedByCustomer",
  "documentsMetaData": [{
    "httpPartName": "mainContent",
    "digest": {
      "value": "4EjzTinrhR8HlO94GsII3RN01zDU8VGLaC0X6l9QrWs=",
      "method": "sha256"
    }
  }]
}

Proof of publication​

After publishing the registered mail, the service returns an overview of the publication including the CAdES-T signature containing the necessary information in order to prove that the registered mail has been sent. An example of the reply can be found below.

Example:

{
    "customerReference": "identifierDefinedByCustomer",
    "messageId": "88djAhtL92Q",
    "type": "messageTypeIdentifier",
    "businessDataList": [],
    "documents": [
        {
            "httpPartName": "mainContent",
            "mediaType": "application/pdf",
            "downloadFileName": "DocumentName.pdf",
            "digest": {
                "value": "4EjzTinrhR8HlO94GsII3RN01zDU8VGLaC0X6l9QrWs=",
                "method": "sha256"
            }
        }
    ],
    "signature": "TUlJZEF3WU******2ZRRGJ5N2M="
}