Table of Contents

Relay API

The three routes share the same address and the same key: only the end of the path changes.

Common rules

  • Key: x-functions-key: <key> header, or ?code=<key> parameter. With RELAY_EXTRA_API_KEY, add the x-relay-key header.
  • Body: JSON. Send the Content-Type: application/json header.
  • Field names: case does not matter (subject or Subject).
  • Strict types: a number or a boolean in quotes, or a string instead of a list, gives 400 Invalid JSON body, without a field name. It is the most frequent error with no-code tools.
  • HTTP code: for the relay's responses, it equals the status field of the body. Azure's refusals (missing or invalid key, unknown route) have no body.
  • Order of checks: x-relay-key, then the JSON, then the relay's configuration (500), then the fields (400). A badly configured relay therefore answers 500, even to an invalid body.

POST /api/enveloppe

Creates a link that you give someone to receive documents from them. The relay does not send it: you send the link.

Field Type Role
subject text Required. Envelope subject, visible to the recipient.
destination text Required. A single email: call the route once per recipient.
culture text fr-CA or en-CA, for this call. By default, SE_DEFAULT_CULTURE.
notifyWhenRead boolean Notifies the person who replied when you open their reply. Default: true.
replyExpirationHours integer Validity of the envelope, in hours. Default: 24, within your licence's retention limit.
maximumReplyOpenTime integer Number of times you can open the reply, from 1 to 99. Default: 1.
authorizedExtensions list Accepted extensions, for example [".pdf", ".jpg"], always as a JSON list. Lowercased, dot added, duplicates removed. Absent: all.
callBackParameters text Data attached to the reply, for example a file number. Kept only if your organization uses SESAR. Nothing confidential.
replyToAPI boolean Deprecated and without effect. 
curl -s -X POST "https://<host>/api/enveloppe" -H "x-functions-key: <key>" -H "Content-Type: application/json" -d '{"subject":"Requested documents","destination":"client@example.com","replyExpirationHours":72,"authorizedExtensions":[".pdf"]}'

{
  "status": 200,
  "url": "https://www.secure-exchanges.com/...&enveloppe=true",
  "repId": "00000000-0000-0000-0000-000000000000",
  "error": null
}

url is the link to send; repId identifies the expected reply.

Code When
400 subject and destination are required, or invalid body
500 Relay is not configured, or internal error
502 No usable response from Secure Exchanges, often the wrong environment
Other 4xx or 5xx Code returned as is by Secure Exchanges

POST /api/message

Sends a secure message. Secure Exchanges sends the email: each recipient gets their own link, and all share the password.

Field Type Role
subject text Required. Email subject.
message text Required. Message body.
recipients list Required, at least one: [{"email": "...", "phone": "+15145551234"}]. A recipient without an email is only accepted with msgSMSOnly.
password text Message password, shared by all recipients. Send it through another channel.
sendMode text onlyEmail by default. msgSMSOnly, msgSMSCodeEmail and msgEmailCodeSms require a phone for each recipient.
culture text fr-CA or en-CA, for this call.
notifyWhenRead boolean You are notified when it is opened. Default: true.
clearTextNotification boolean Opening notification in clear text rather than encrypted. Default: false.
maximumOpenTime integer Number of openings before destruction, from 1 to 99. Default: 5.
expirationMinutes integer Lifetime of the message, greater than 0. Default: 50,400, that is 35 days.
senderName text Name shown as the sender.
callBackParameters text Data returned when the message is read. Nothing confidential. 
curl -s -X POST "https://<host>/api/message" -H "x-functions-key: <key>" -H "Content-Type: application/json" -d '{"subject":"Your documents","message":"Hello, your documents are ready.","recipients":[{"email":"client@example.com"}]}'

{
  "status": 200,
  "recipients": [
    {
      "email": "client@example.com",
      "status": 200,
      "url": "https://www.secure-exchanges.com/...",
      "messageId": "...",
      "trackingId": "00000000-0000-0000-0000-000000000000",
      "openingCode": null
    }
  ],
  "error": null
}

Check the status of each recipient, not only the top-level one. The relay first validates all recipients: an error names the faulty line, for example recipients[1]: email is required (only sendMode msgSMSOnly accepts a phone-only recipient), with the index starting at 0. If Secure Exchanges then refuses a recipient, the sending can stop there: the response is then an error, and recipients lists those already served.

The email has already left: url is given for information. Do not redistribute it, it gives access to the message.

Code When
400 Required field missing, unknown sendMode, maximumOpenTime outside 1 to 99, zero or negative expirationMinutes, invalid recipient, invalid body
500 Relay is not configured, or internal error
502 No usable response from Secure Exchanges
Other 4xx or 5xx Code returned as is by Secure Exchanges, for example 403 with the wrong environment

GET /api/version

No body. Gives the installed version and the latest published version.

{
  "status": 200,
  "version": "1.2.0",
  "publishedVersion": "1.2.0",
  "updateAvailable": false,
  "operations": ["POST /api/enveloppe", "POST /api/message", "GET /api/version"],
  "error": null
}

This route does not call Secure Exchanges and does not read your credentials: a 200 response proves that the code is installed and the key is valid, not that the configuration is correct. It answers 200, or 401 with RELAY_EXTRA_API_KEY.

publishedVersion and updateAvailable are null when the published version file could not be read: RELAY_PACKAGE_URL address missing, 5-second timeout exceeded or unreadable content. Everything else works normally.