Table of Contents

Notifications and callback parameters

Know when a message is opened, and link a message to your own data.

What the SDK offers

Need Means
Be notified that a message was opened getNotify: an email notifies the account holder when the message is opened.
Know the state of a message The logs: openings, downloads, signature.
Link a message to your data CallBackParameters: data that travels with the message and that you read back with it.
Receive replies to envelopes in your system SESAR: it receives a copy of each reply, with its CallBackParameters. SESAR Webhook passes them to your systems: see Classify drops.

The SDK provides no endpoint for notifications pushed to your service. To track your messages automatically, poll the logs at regular intervals, over a short period.

Callback parameters

Attach an internal identifier to the send, for example a file number: you get it back when the message is read, or with the reply to an envelope.

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, getNotify: true, cultureID: "en-CA",
    maximumOpenTime: 5, minutesExpiration: 10080)
{
    // List of Key / Value pairs: the recommended format
    CallBackParameters = JsonConvert.SerializeObject(new List<CallBackParameter>
    {
        new CallBackParameter("FileNo", fileNumber),
    }),
};

// When reading (see Read a message):
string parameters = response.CallBackParameters;
Point Detail
Confidentiality This data is not confidential: Secure Exchanges and anyone who reads the message with the SDK can read it. Only put an internal identifier in it, never personal information or a secret.
Format A free string. Preferably use a list of Key / Value pairs, as in the example: see Callback parameter format.
Reading Validate it like any external data: expected format, existing file, and the user's right to that file.
Envelopes and signature The same field exists for envelopes and for a send of documents to sign.
.NET Framework The SDK embeds Newtonsoft.Json without exposing it: add the Newtonsoft.Json NuGet package to your project to use JsonConvert.
With SESAR The parameters come back in the manifest of each drop: the most reliable way to file it in the right folder. See Classify drops.

Callback parameter format

The SDK accepts any string. Preferably use a JSON list of Key / Value pairs, as in the example: [{"Key":"FileNo","Value":"A-1042"}]. It is the form that Secure Exchanges tools use; in .NET, the CallBackParameter class produces it.

For the names (Key), use your organization's contextual keys: field names that an administrator defines in the portal (Organization > Contextual keys), so that all your sends use the same names. GetSerialInfo returns them:

SDK Property Content
.NET ContextualKeys List of ContextualKey: Key, CreatedDate.
Python contextual_keys List of dictionaries: "Key", "CreatedDate".
PHP contextualKeys Array of associative arrays: 'Key', 'CreatedDate'.

The list is empty if your organization has defined no key, and null if the licence belongs to no organization. A contextual key is only a name: it is neither a secret nor an access right.

Be notified of an opening

With getNotify set to true, the account holder receives an email when the message is opened. For automated processing, prefer the logs: each recipient's status can be read by the SDK.

For envelopes, NotifyWhenRead notifies the person who replied when you open their reply.

Common errors

Symptom Likely cause Solution
.NET: SerializationHelper.DeserializeFromJson or CryptoHelper.DecryptStringFromB64 not found Methods from a former guide, which do not exist Use JsonConvert for JSON, and GetMessage to read the message.
No notification email getNotify set to false, or message not opened yet Check the option at send time, then the state in the logs.

Next