Read a message

Open a received Secure Exchanges message with the SDK, from its link: subject, body and attachments.

Prerequisites

Your credentials: see Credentials and environments.
The full link of the message, with all its parameters.

Warning

The link is a secret. It gives access to the message. Do not log it, do not put it in one of your application's URLs, and do not keep it longer than needed.

Steps

Parse the link with GetSecureExchangesMessageFromLink.
If the message is protected, ask the user for the password or the opening code. The link tells what to ask for.
Call GetMessage, then check the status.
For attachments, see Download received files.

Example

SecureExchangesMessage msg = MessageHelper.GetSecureExchangesMessageFromLink(link);

// Asked from the user, never written in code.
string password = msg.Password ? AskPassword() : null;
string code = msg.Digit ? AskOpeningCode() : null;

var args = new GetMessageArgs(endpoint, serial, apiUser, apiPassword, msg, password: password, digit: code);
GetMessageResponse response = MessageHelper.GetMessage(args);

if (response.Status == 200)
{
    // response.Subject, response.Message (HTML) and response.FilesMetaData
    Process(response);
}
else
{
    logger.LogWarning("Read refused, status {Status}", response.Status);
}

try:
    msg_params = MessageHelper.get_secure_exchanges_message_from_link(link)
except ValueError:
    msg_params = None
if msg_params is None:
    raise InvalidLink()

# Asked from the user, never written in code.
password = ask_password() if msg_params.get("password") else None
code = ask_opening_code() if msg_params.get("digit") else None

response = MessageHelper.get_message(
    api_client=client, sems_client=sems_client,
    serial=serial, api_user=api_user, api_password=api_password,
    msg_params=msg_params, password=password, digit_code=code,
)

if response.status == 200 and response.message is not None:
    # response.subject, response.message (HTML) and response.secure_files
    process(response)
else:
    logger.warning("Read refused, status %s", response.status)

$msgParams = MessageHelper::getSecureExchangesMessageFromLink($link);
if ($msgParams === null) {
    throw new InvalidLinkException();
}

// Asked from the user, never written in code.
$password = ($msgParams['password'] ?? false) ? askPassword() : null;
$code = ($msgParams['digit'] ?? false) ? askOpeningCode() : null;

$response = MessageHelper::getMessage(
    apiClient: $client, semsClient: $sems,
    serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
    msgParams: $msgParams, password: $password, digitCode: $code,
);

if ($response->status === 200) {
    // $response->subject, $response->message (HTML) and $response->secureFiles
    process($response);
} else {
    $logger->warning('Read refused, status ' . $response->status);
}

The response

Content	Where to find it
Subject and body (HTML)	See the comments in the example.
Attachments	`FilesMetaData`: to pass to the download.
Remaining openings	`RemainingOpenTime`
Expiry	`ExpireOn`

Dates (ExpireOn) may come as a string rather than a date: convert them before comparing.

Openings and password

Situation	Effect
Each call to `GetMessage`	Counts as an opening, whether it succeeds or not.
Last allowed opening	The message is returned, then destroyed. The next call receives status 404.
Wrong password or opening code	The server refuses the read with status 404, the same as for an expired or deleted message: the response does not say which. The attempt counts as an opening.

So never retry a read automatically: ask the user for the password or code again, and limit the number of attempts on your side. In the logs, a successful read shows as retrieved (Retreive), and a destroyed message as Destroy.

Handle decrypted content

The subject, body and files are in plain text in your application.

Logs and console: never write the subject, the body or file names to them.
Storage: keep them encrypted, restrict who can access them, and delete them as soon as they are no longer needed. See Encryption.
Web display: the body is HTML written by the sender. Never insert it as is in a page (innerHTML, @Html.Raw, echo): clean it with an allowlist of tags, or display it in an isolated iframe (sandbox, no scripts).
Errors: the error text returned by the SDK may contain technical details. Show a generic message and keep the status in your logs.

Common errors

Symptom	Likely cause	Solution
.NET: `FormatException` when parsing the link	Truncated or modified link	Use the full link, untouched.
Python: `ValueError` when parsing the link	Same cause	Same solution; catch the exception, as in the example.
PHP: `TypeError` in `getMessage`	The link could not be parsed (`null`)	Check the result before the call, as in the example.
Status 404	Wrong password or opening code, or message expired, deleted or out of openings	Check what the link asks for, then ask the user again, without retrying automatically.
Python: status 200 but empty body (`None`)	The body could not be decrypted	Treat this case as a failure, as in the example.
.NET: `response.Body`, `file.FileName` or `file.MimeType` not found	Names from the former guides	Use `response.Message`, `file.RealFileName` and `file.FileType`.

Table of Contents