Message lifecycle
What happens from sending a message to its end of life: link, openings, notifications, expiry and deletion.
The stages
| Stage | What happens |
|---|---|
| 1. Send | The SDK encrypts the body and the files in your application, then uploads them to Secure Exchanges. Each recipient gets their own link and their own tracking number. |
| 2. Delivery | With getBackHtml set to false, Secure Exchanges sends the email (or the SMS). Set to true, the SDK returns the email as HTML: your application must send it, otherwise the recipient receives nothing. |
| 3. Opening | The recipient opens the link, with the password or opening code if there is one. Each opening uses one of the allowed openings, including a read through the SDK. |
| 4. Notification | With getNotify set to true, the licence holder receives an email when the message is opened: see The notification email. |
| 5. Tracking | The logs show, for each recipient, openings, downloads and signature. |
| 6. End of life | The message expires after the chosen duration, when its openings are used up, or when you delete it: see End of life. |
Parameters that govern a message's life
| Parameter | Role | Default value |
|---|---|---|
minutesExpiration |
Lifetime of the message, in minutes. | 10080, i.e. 7 days, in Python and PHP; required in .NET. |
maximumOpenTime |
Number of allowed openings, from 1 to 99. | 1 in Python and PHP; required in .NET. |
getNotify |
Email notification to the account holder on opening. | true in Python and PHP; required in .NET. |
getBackHtml |
Who sends the email: Secure Exchanges (false) or your application (true). | true in Python and PHP; required in .NET. |
The maximum duration depends on your licence: see MaxMinMsgRetention in Licence and quotas.
What the send returns
For each recipient:
| Item | What to do with it |
|---|---|
| Status | Check it: a send can succeed for one recipient and fail for another. See Multiple recipients. |
Tracking number (TrackingID) |
Keep it: it is used for logs and deletion. |
| Link and HTML email | These are secrets: give them only to the recipient and never log them. |
When reading
The read response gives the number of remaining openings (RemainingOpenTime) and the expiry date (ExpireOn), equal to the send date plus minutesExpiration. See Read a message.
Replies
A reply to an envelope is linked by Secure Exchanges to the original request. In the logs, it shows up as a reply (MsgType set to 2).
End of life
| Event | What happens |
|---|---|
| Last allowed opening | The recipient sees the message one last time, then the server destroys it with its files. The log adds a Destroy activity, but its status stays the retrieval one (Retreive). |
| Expiry | The link no longer leads to the message, and the server then erases it with its files. The log status does not change: its ExpirationDate field gives the expiry date. |
| Deletion | The message is destroyed with its files, the log moves to status Destroy, and the licence holder receives a confirmation email. See Delete a message. |
The notification email
With getNotify set to true, the holder of the licence that sent the message receives an email when the recipient opens it, in their account's language. Its subject is "Your message has just been read by", followed by the recipient's address. It gives the recipient, the message's subject, the send date and the opening date, in the account's time zone. If your organization turned on geolocation for notifications, it also gives the country, the city and the IP address the message was opened from.
The message's subject appears in plain text in that email: do not put more personal information in it than needed.