Table of Contents

Envelopes

Request documents or an answer from someone securely. The SDK creates an envelope: a link to an encrypted reply form, specific to each recipient.

Prerequisites

Your credentials: see Credentials and environments.

One person

GetEnveloppe returns the envelope's address. Your application is the one that gives it to the person.

var args = new GetEnveloppeArgs(endpoint, serial, apiUser, apiPassword,
    subject: "Supporting documents",        // in plain text in the envelope link
    destination: "client@example.com",      // sender of the reply: valid address
    cultureID: "en-CA")
{
    MaximumReplyOpenTime = 3,                // otherwise a single opening in .NET
    ReplyExpirationHours = 72,
    AuthorizedExtensions = new[] { ".pdf", ".jpg" },
};

GetEnveloppeResponse response = MessageHelper.GetEnveloppe(args);

if (response != null && response.StatusCode == 200)
{
    Uri link = response.Url;   // to give to the person; do not log it
}

Several people

GetEnvelopes creates one envelope per person. A phone number adds a check by SMS code before the form can be accessed.

var people = new List<Recipient>   // SecureExchangesSDK.SecureExchanges.Recipient
{
    new Recipient { Email = "client@example.com", Phone = "+15145550123" },
    new Recipient { Email = "spouse@example.com" },
};

var args = new GetEnvelopesArgs(endpoint, serial, apiUser, apiPassword,
    "Supporting documents", people, "en-CA")
{
    MaximumReplyOpenTime = 3,
    ReplyExpirationHours = 72,
};

GetEnvelopesResponse response = MessageHelper.GetEnvelopes(args);

foreach (GetEnveloppeResponse envelope in response.Answers)
{
    if (envelope.StatusCode == 200)
        Deliver(envelope.Recipient, envelope.Url);
    else
        logger.LogWarning("Envelope refused, status {Status}", envelope.StatusCode);
}

Pass each person as a dictionary (associative array) with Email and Phone keys, not as a RecipientInfo object: in Python, the person would be left out of the response; in PHP, the call would fail.

Options

Option Default Role
MaximumReplyOpenTime 3 in Python and PHP; 1 in .NET Number of times you can open the reply, from 1 to 99.
ReplyExpirationHours 24 How long the envelope stays valid, in hours, within the licences' retention limit.
AuthorizedExtensions All types Accepted file types, for example .pdf.
NotifyWhenRead true Notifies the person who replied when you open their reply.
ReplyOptions None NoEditor hides the text editor: the reply must then contain at least one file. Password lets the person protect their reply with a password. NoSign prevents them from requesting a signature on the files they attach.
CallBackParameters None Data attached to the reply, for example a file number. It is kept only if your organization uses SESAR: it then comes with the copy of each reply that SESAR receives. Without SESAR, it is ignored. Format: see Callback parameter format.
ReplyToAPI false Obsolete, no effect: the server ignores it. Do not use it.

In .NET, no constructor gives a value to MaximumReplyOpenTime or ReplyExpirationHours: without them, the reply can be opened only once and the envelope stays valid 24 hours. Set them to get the Python and PHP behaviour.

In PHP, replyOptions expects an array: pass $options->toArray() if you use the SeReplyOptions class.

Warning

File types. Invalid extensions are removed from the list, and an empty list means accept everything. A typo in every extension therefore lifts the restriction without any error. Write extensions in lower case, with the dot (.pdf), especially in .NET, which does not add it, and check your list with a test.

Good to know

  • The link is personal. It gives access to the form: give it only to the person concerned and do not log it. Add a phone number to also require an SMS code.
  • Phone. No SDK validates the envelopes' number: validate it yourself with IsValidPhoneNumberAndCanReceiveSMS, in international format.
  • Subject and destination. The subject is in plain text in the envelope link. The destination becomes the sender of the reply: each address must be valid, separated from the others by ;. Do not put more personal information in them than needed.
  • The reply reaches you as a Secure Exchanges message, at the address of the holder of the licence that created the envelope. If your organization uses SESAR, it also receives a copy.
  • CallBackParameters. Only put internal identifiers in it, never personal information in plain text.
  • Status. Check StatusCode for each envelope. The error message field is never filled for envelopes.

Common errors

Symptom Likely cause Solution
.NET: NullReferenceException after MessageHelper.GetEnveloppe The method returned null: credentials refused or wrong environment Test for null, as in the example, then check your credentials.
Status 500 when creating the envelope Invalid destination address Check each address; separate them with ;.
The file type restriction has no effect Invalid extensions, or without the dot Write .pdf, not pdf or *.pdf.
Python: a person is missing from the response Person passed as an object Pass a dictionary {"Email": ...}.
PHP: fatal error in getEnvelopes Person passed as an object Pass an array ['Email' => ...].
PHP: TypeError on replyOptions SeReplyOptions object passed as is Pass ->toArray().

Next