Send a message

Send an encrypted message to one or more recipients. Each recipient gets a unique link.

Prerequisites

A configured client and your credentials loaded: see Credentials and environments.

Example

The method to call is MultiRecipientMessage. The complete, runnable example is in First message in 5 minutes.

var args = new MutliRecipientArgs(
    endPointUri: endpoint, serial: serial, user: apiUser, psw: apiPassword,
    recipients: recipients, message: message, subject: subject,
    password: null, filesList: null,
    sendMode: SendMethodEnum.onlyEmail, getBackHtml: false,
    showSubject: true,   // obsolete, no effect, but required by the constructor
    getNotify: true, cultureID: "en-CA",
    maximumOpenTime: 5, minutesExpiration: 1440);

var response = MessageHelper.MultiRecipientMessage(args);

answer = MessageHelper.multi_recipient_message(
    api_client=client, sems_client=sems_client,
    serial=serial, api_user=api_user, api_password=api_password,
    recipients=[RecipientInfo(email="recipient@example.com")],
    message=message, subject=subject,
    get_back_html=False, culture_id="en-CA", maximum_open_time=5,
)

$answer = MessageHelper::multiRecipientMessage(
    apiClient: $client, semsClient: $sems,
    serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
    recipients: [new RecipientInfo(email: 'recipient@example.com')],
    message: $message, subject: $subject,
    getBackHtml: false, cultureId: 'en-CA', maximumOpenTime: 5,
);

Options

The MutliRecipientArgs constructor requires all these values, except createMessageCopy; use named arguments to keep the code readable.

Option	Purpose
`recipients`	Recipients: email, and phone number for SMS delivery.
`message`, `subject`	Content (HTML allowed) and subject.
`password`	Password requested when opening, or null. Share it through another channel than email.
`sendMode`	Email only, SMS only, email with SMS code, or SMS with email code.
`getBackHtml`	false: Secure Exchanges sends the email. true: the SDK returns the email as HTML, for you to send.
`maximumOpenTime`	Number of times the message can be opened, from 1 to 99.
`minutesExpiration`	How long the link stays valid, in minutes.
`showSubject`	Obsolete, no effect: the constructor still requires it, but its value is ignored.
`getNotify`	Notifies you when the message is opened.
`cultureID`	Language of the email and of the reading page, for example `fr-CA`.
`createMessageCopy`	Obsolete: no longer supported. Only some constructor overloads accept it: do not use them.

Only recipients, message and subject are required. Watch the default values of getBackHtml and maximumOpenTime: they are the two most frequent causes of support questions.

Option	Default	Purpose
`recipients`	required	Recipients: email, and phone number for SMS delivery.
`message`, `subject`	required	Content (HTML allowed) and subject.
`password`	none	Password requested when opening. Share it through another channel than email.
`sendMode`	email only	Email only, SMS only, email with SMS code, or SMS with email code.
`getBackHtml`	true	false: Secure Exchanges sends the email. true: the SDK returns the email as HTML, for you to send.
`maximumOpenTime`	1	Number of times the message can be opened, from 1 to 99.
`minutesExpiration`	10,080 (7 days)	How long the link stays valid, in minutes.
`showSubject`	none	Obsolete, no effect: do not pass it. Passing it emits a warning.
`getNotify`	true	Notifies you when the message is opened.
`cultureID`	en-US	Language of the email and of the reading page, for example `fr-CA`.
`createMessageCopy`	false	Obsolete: no longer supported.

Send the email yourself

With getBackHtml set to true, Secure Exchanges sends nothing. For each recipient, the response (RecipientsAnswer) holds what you need to send the email yourself:

Field	Content
`HtmlMsg`	The HTML body of the email, with the message link: send it as is to the recipient.
`URL`	The message link alone, if you pass it on another way.
`DefaultOpeningCode`	The opening code, filled only if your organization requires an opening code included in the email. It is already in `HtmlMsg`.

foreach (var ra in response.RecipientsAnswer)
{
    if (ra.Answer?.Status != 200) continue;   // see Multiple recipients
    // The HTML carries the message link: it is a secret, do not log it
    SendEmail(ra.Recipient.Email, subject, ra.Answer.HtmlMsg);   // your own sending function
}

for ra in answer.recipients_answer:
    if ra.answer and ra.answer.status == 200:
        # The HTML carries the message link: it is a secret, do not log it
        send_email(ra.recipient.email, subject, ra.answer.html_msg)  # your own sending function

foreach ($answer->recipientsAnswer as $ra) {
    if ($ra->answer !== null && $ra->answer->status === 200) {
        // The HTML carries the message link: it is a secret, do not log it
        sendEmail($ra->recipient->email, $subject, $ra->answer->htmlMsg);   // your own sending function
    }
}

The link and the opening code give access to the message: hand them only to the recipient, and copy them neither into your logs nor into a tracking tool.

Common errors

Symptom	Likely cause	Solution
Status 401	Wrong credentials, or production credentials used in preview	Check the three credentials and the environment.
Status 403	Invalid or expired licence	See Licence and quotas.
Status 400	Invalid parameter (email, file size)	Check the parameters you send.
Status 200, but no email received	`getBackHtml` set to true	Set it to false, or send `HtmlMsg` yourself: see Send the email yourself.
The recipient can no longer open the message	`maximumOpenTime` reached	Increase the number of allowed openings.