Secure Messaging API

Transcription

1 Secure Messaging API Admin User Guide Intrductin... 2 Client Services API Framewrk Sample... 2 API Services... 2 Authenticatin and Security... 2 JSON Request / Respnse frmat... 2 Request structure... 3 Respnse structure... 4 HTTP Headers... 5 Cntent Type... 5 Ckies Cmmand X-Header... 5 Errr handling... 6 API Cmmands... 7 Authenticatin services... 7 Lgin... 7 Authenticate Frgt Passwrd User / Member prvisining services Get Member Add Member Update Member Secure messaging services Pre Create Message Save Message Send Message Get Message List Get Message Details Delete Message Appendix: 2 JSON Data Types Number Blean DateTime List / Array Object Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 1 f 65

2 Intrductin The Secure Messaging Platfrm Applicatin Prgramming Interface (API) allws third-party develpers t request data and initiate prcesses with a specific custmer Prtal. This data can then be used r manipulated utside f the Secure Messaging Platfrm, and in sme cases, can be returned t the Secure Messaging platfrm. Client Services API Framewrk Sample This sample client applicatin framewrk (SDK) is a Visual Studi 2010.Net 4 class library that implements the mst cmmn cmmands available in the API. API Services Sample.NET prject: T execute an peratin using the API, yu need t submit an HTTP POST request t the URL that crrespnds t the Secure Messaging platfrm yu are accessing cntaining the peratin that yu wish t perfrm as a JSON bject in the bdy f the request. The utput f the cmmand is returned t yu as a JSON bject in the bdy f the HTTP respnse. In rder t get started, yu will need t btain the fllwing infrmatin frm yur accunt manager (the infrmatin prvided in this dcument is nly a sample and des nt wrk): penguid = 42e a8-4ce9-ab99-e b4 penname = ABC Medical Secure servicesurl = hmeurl = where crrespnds t the URL f the Secure Messaging platfrm server URL hsting the custmer platfrm and the cde crrespnd t the Secure Messaging platfrm cde used t access the Secure Message Center (Webmail). Authenticatin and Security The API is nly available thrugh a secure HTTPS channel. Accessing the API via a regular HTTP channel will result in a 500 HTTP errr cde returned by the server. Each API request that yu send need t cntain a sessin tken, which will be use t authrize access t the peratin specified in the API request. Sessin tkens are nly available t active users and administrative users f the Secure Messaging platfrm, and thse tkens nly authrize peratins within the same Secure Messaging platfrm. By default, sessin tkens expire after 60 minutes. As such, yu will need t submit a request t the abve URL at least nce every hur. NOTE: It is recmmended that yu keep the tken in memry rather than writing it t a file. The API als includes an autmatic thrttling mechanism t avid abuse. This mechanism will ban specific users, cmputers r IP addresses that query the system t frequently r in an imprper manner. Nte that there are ther criteria available t administratrs t allw / ban ther users r IP addresses. JSON Request / Respnse frmat Accessing the API must be dne sending HTTP POST requests t the crrespnding Secure Messaging platfrm server with the bdy f the request using a JSON bject. The respnse will als be represented as a JSON bject. The API s request/respnse JSON bjects fllw the specificatin described belw. Fr details abut the syntax supprted by the JSON values refer t Appendix A: JSON Data Types. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 2 f 65

3 Request structure An API Request crrespnds t an unnamed JSON bject with tw mandatry bjects within: header and data. The example belw shws the bdy f the HTTP request used by a third party applicatin t authenticate with a Secure Messaging platfrm and retrieve a sessin tken. 01 POST /services/api.aspx HTTP/ { 04 "header": { 05 "cmmand": "lgin", 06 "timestamp": new Date( ), 07 "clientname": "OL ", 08 "clientversin": " " 09 }, 10 "data": { 11 " address": "user.ne@crp-natinal.cm", 12 "passwrd": "p455w0rd" 13 } 14 } NOTE: The text in this example has been frmatted fr readability purpses nly. Header sectin The Request Header is a mandatry JSON bject named header with the fllwing JSON values as parameters: tken The sessin validatin tken returned nce yu've lgged int the system. / Optinal Authenticatin cmmands d nt require this value, but all messaging-related cmmands need it. The tken is valid nly fr the length f the sessin. Third party applicatins must keep the sessin alive (using ckies) in rder t be able t use the API Services. cmmand One f the pssible cmmands supprted as listed belw in the API Cmmand sectin. / Mandatry timestamp The date and time f the request expressed in GMT/UTC frmat. DateTime / Mandatry clientname / Mandatry Specifies the name f the third party applicatin requesting cmmands. This is a mandatry field but its value is nt restricted t any specific cnventin. Yu are free t use this value fr yur wn purpses and fllw yur wn ntatin. Hwever, the API can respnd t a specific list f apprved applicatins in a custmized way. Sme applicatins, such as the Secure MS Outlk Tlbar have available extended parameters and sme specific cmmands available t it. clientversin / Mandatry Indicates the third party applicatin versin number. This value helps the applicatin synchrnizing with the apprpriate versin f the API. Optinal parameters d nt need t be included in the request. Fr example, the lgin cmmand shwn in the example abve des nt require a tken parameter as this value will be returned by the crrespnding respnse. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 3 f 65

4 Data sectin The Request Data is a mandatry JSON bject named data with a list f JSON values as input parameters. Each individual cmmand specifies if the crrespnding request parameter is mandatry r ptinal and the data type f the parameter. Respnse structure An API Respnse crrespnds t an unnamed JSON Object with tw bjects within: header and a data. The example belw shws the respnse that is sent when a third party applicatin authenticates with a Secure Messaging platfrm and receives a sessin tken back OK { 04 "header": { 05 "cmmand": "lgin", 06 "timestamp": new Date( ), 07 "errrcde": 0, 08 "errrdesc": "", 09 "serverversin": " " 10 } 11 "data": { 12 "tken": "Y642AV2B-73F3-479B-81FE-FA48H9835BF2", 13 } 14 } Header sectin The Respnse Header is a JSON bject named header with the fllwing JSON values as parameters: cmmand / Mandatry Cmmand is ne f the pssible cmmands listed belw in the API Cmmands sectin. It crrespnds t the cmmand sent in the request. timestamp The date and time f the respnse expressed in GMT /UTC frmat. DateTime / Mandatry errrcde Indicates the errr cde as specified by the Secure Messaging platfrm server. Number / Mandatry If the request was prcessed successfully the system will return 0 (zer). If there was a prblem prcessing the request cmmand, the respnse will include the apprpriate errr cde in this utput parameter. Each cmmand describes the errr cdes available. errrdesc Errr descriptin crrespnding t the errr cde included in the previus parameter. / Mandatry If there are n errrs, this parameter returns an empty string. The errr message returned by the server includes nly generic infrmatin abut the issue fund. Develpers are encuraged t add t this infrmatin in the cntext f where the prblem ccurred. In sme ccasins it is a gd idea t replace the message altgether by an apprpriate cntextual message. serverversin / Mandatry Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 4 f 65

5 Indicates the API Services versin number. As with the request specificatin, ptinal parameters d nt need t be included in the respnse. Sme extensins t the Secure Messaging platfrm Server may nt include ptinal parameters r sme specific clients require extra parameters that ther applicatins d nt. Data sectin The Respnse Data sectin is an ptinal JSON bject named data with a list f JSON values as utput parameters. Sme cmmands d nt return any data. In these cases the data sectin may be mitted. Each cmmand specifies if the respnse parameters are mandatry r ptinal and the data type f each parameter. Typically, when the system finds an errr fr a given request, the respnse cntains nly a header sectin with the apprpriate errr cde and descriptin with an empty data sectin. Hwever, sme errr cdes returned by the server may include extra infrmatin, in which case the data sectin is als included in the respnse (e.g., the banned wrd when this rule is brken by a message that cntains banned wrds). HTTP Headers All API requests must include the fllwing HTTP headers: Cntent Type The POST request must specify the value applicatin/x-www-frm-urlencded fr the Cntent-Type header. Ckies Fr security reasns, interacting with the API requires that the client stres the HTTP Ckie sent by the Secure Messaging platfrm server the first time yu initiate an HTTP cnnectin. Als, preserving the HTTP sessin using this ASP.NET Ckie helps t increase the security and perfrmance f the system. Subsequent calls t the same Secure Messaging platfrm using this tken require yu t pass the ckie in the HTTP headers in rder t preserve the sessin state in the server. Failure t d this will result in new server sessins created fr each HTTP cnnectin t the server rendering the tken sessin useless. 2 Cmmand X-Header As an extra cntrl mechanism the API requires yu t include the cmmand cde as an extended HTTP header named X- 2Cmd. This is the same cmmand cde included in the bdy f the request in the JSON header. Cnsider the fllwing examples that shws the HTTP headers exchange fr the lgin and getmember cmmands (Ntice that in this example the fcus is n the HTTP headers, nt the actual cmmand): First Request: 01 POST /services/api.aspx HTTP/ User-Agent: 2client 03 X- 2Cmd: lgin 04 Cntent-Type: applicatin/x-www-frm-urlencded; charset=utf-8 05 Hst: vmqa1: Cntent-Length: Expect: 100-cntinue 08 Cnnectin: Clse {"data":{" address":"user.fur@crp-natinal.cm","passwrd":"1324"},"header":{"cmmand":"lgin","timestamp":new Date( ),"clientName":"apiNetTest","clientVersin":" "}} Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 5 f 65

6 In this case, in line number 3 we specify as an X-Header attribute the cmmand cde als cntained in the bdy f the request starting in line number 10. Line 4 shws hw t specify the cntent-type header. Ntice that the hst vmqa1:9999 (line 5) is nly an example. Respnse: 01 HTTP/ OK 02 Server: Micrsft-IIS/ Date: Wed, 31 Dec :07:30 GMT 04 X-Pwered-By: ASP.NET 05 Cnnectin: clse 06 X-AspNet-Versin: Set-Ckie: ASP.NET_SessinId=mg4idv55a0e2kmuqivt5prm; path=/; HttpOnly 08 Cache-Cntrl: private 09 Cntent-Type: text/html 10 Cntent-Length: {"data":{"tken":"1ea13a3d-ebc3-44ed-9392-cb5dca16a704"}, "header":{"cmmand":"lgin","timestamp":new Date( ),"errCde":0,"errDesc":"","serverVersin":" "}} Ntice line number 7 (in bld) where the server returns the HTTP Ckie with the ASP.NET sessin. Yu need t preserve this value alng with the sessin tken returned in line 12. Subsequent calls need t preserve this value as shwn in the fllwing request t btain the member s prfile: 01 POST /services/api.aspx HTTP/ User-Agent: DesktpAgent 03 Ckie: ASP.NET_SessinId=mg4idv55a0e2kmuqivt5prm 04 X- 2Cmd: getmember 05 Cntent-Type: applicatin/x-www-frm-urlencded; charset=utf-8 06 Hst: vmqa1: Cntent-Length: Expect: 100-cntinue 09 Cnnectin: Clse {"data":{" address":"user.fur@crp natinal.cm"},"header":{"cmmand":"getmember", "timestamp":new Date( ),"tken":"1ea13a3d-ebc3-44ed cb5dca16a704","clientname":"apinettest","clientversin":" "}} In this secnd request, besides sending the cmmand in the header as shwn in line number 4, the ASP.NET Ckie is als passed back t the server in the apprpriate frmat in line number 3. Errr handling When integrating a third party applicatin with the API yu must lk fr successful cmmands at tw levels. First, yu need t check the actual HTTP errr cde returned by the cmmunicatin channel. In general, a successful respnse cntains errr cde 200 (OK). The API des nt make use f any ther HTTP errr cde t reprt an errr. If yu receive an errr cde ther than 200, yu must fllw a standard actin as fr any web applicatin. Fr mre infrmatin abut standard HTTP errr cdes yu can review the fllwing link: If the HTTP cmmand succeeded (200, OK), the success f the cmmand is included in the header JSON bject f the Respnse. Each cmmand includes a sectin with the list f errr cdes supprted by that cmmand. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 6 f 65

7 API Cmmands The current versin f the API supprts the cmmands described in this sectin. The cmmands are gruped in three majr sectins: Authenticatin services Member prvisining services Secure messaging services Each sectin includes a summary with a high-level descriptin f the cmmands included in it and then subsectins with the details fr each cmmand, including the request and respnse parameters supprted by the cmmand, fllwed by a list f errr cdes, and examples. The descriptin prvided fr each cmmand fcus n their data sectin. The header sectin f the JSON request/respnse fllws the guidelines described in the JSON Request / Respnse sectin. The examples prvided fr each cmmand fcus n the JSON bdy f the request/respnse, leaving ut the HTTP headers used in the actual cmmunicatin. The frmat f the actual HTTP request/respnse must fllw the guidelines explained in the HTTP Headers sectin. Authenticatin services Befre yu can use any f the cmmands prvided by the API, yu need t btain a valid sessin tken with the crrespnding Secure Messaging platfrm server. The fllwing cmmands are available in this sectin: Lgin Lgs int a Secure Messaging platfrm (specified by the crrespnding URL) using the supplied credentials. If successful, the Lgin cmmand will return a sessin tken which can be used t invke ther cmmands frm the server during the length f the sessin. Yu must prvide an active user s address t authenticate with the Secure Messaging platfrm. Register Member* Cnfirm Registratin* Frgt Passwrd Initiates the full registratin prcess fr a new user. The new user will receive a basic message ntificatin t cnfirm wnership f the address. The ntificatin cntains a keywrd that must be used t cmplete the registratin. Cnfirm registratin fr new user. Must be cmpleted after registratin and befre lgin. Initiate the prcess t recver access t a Secure Accunt. It sends the crrespnding user an ntificatin with a link t change their passwrd. The user must be registered. Lgin Cmmand cde: lgin The purpse f the lgin cmmand is t authenticate the user and btain a sessin tken t be used in subsequent cmmands t cnsume the services prvided by the API. T btain a sessin tken yu need a valid user s address r the userid f an authrized Secure Messaging platfrm administratr. Depending n the credentials used, the sessin tken will give yu access t different cmmands in the API. The syntax described belw crrespnds t the authenticatin mechanism available fr a user. Please refer t the Examples sectin belw fr the full syntax f the HTTP Request and Respnse. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 7 f 65

8 Request parameters address Valid user Address. The address uniquely identifies the user. / Mandatry Depending n the privileges assigned t the user, the sessin tken btained will give access t different cmmands and t specific infrmatin returned by these cmmands. In general, a user can retrieve and change their wn infrmatin and btain limited infrmatin abut ther users. Sme administrative users can als prvisin new users r update their prfiles. passwrd Passwrd t lgin t the services. / Mandatry requestauthkey Blean / Optinal Default: false Use the requestauthkey parameter with value true t btain an authrizatin key in the respnse which yu can cache in yur lcal applicatin and use in lieu f ladress and passwrd with the authenticate cmmand. Respnse parameters tken authkey This is the glbal unique identifier fr the sessin initiated with this Secure Messaging platfrm. The sessin tken is valid thrughut the length f the sessin initiated with the server and must be used with all subsequent cmmands. Sessins expire after a given amunt f time, at which time yu need t btain a new sessin tken. Sessin tkens can be used nly frm the remte lcatin frm where it was btained. The authkey is an authrizatin key that can be used with the authenticate cmmand t btain a new sessin withut having t pass an address and passwrd. Errr cdes Unexpected / Unknwn lgin errr. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) User is nt registered User is in pending registratin status Attempting t lgin / register n a clsed Secure Messaging platfrm. Yu must be invited t this Secure Messaging platfrm by an existing Prfessinal user Address r Passwrd incrrect System cnfiguratin errr btaining sessin tken. If yu receive this errr cde please cntact supprt immediately. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 8 f 65

9 Examples The fllwing example attempts t btain a sessin tken with the test vmqa1:9999 PEN. In this case the full HTTP headers are included t shw hw the X- 2Cmd X-Header field is used. Ntice that the bdy f the request has been frmatted fr readability purpses nly: 01 POST /services/api.aspx HTTP/ User-Agent: 2client 03 X- 2Cmd: lgin 04 Cntent-Type: applicatin/x-www-frm-urlencded; charset=utf-8 05 Hst: vmqa1: Cntent-Length: Expect: 100-cntinue 08 Cnnectin: Clse { 11 "header": { 12 "cmmand":"lgin", 13 "timestamp":new Date( ), 14 "clientname":"apinettest", 15 "clientversin":" " 16 }, 17 "data": { 18 " address":"user.tw@crp-natinal.cm", 19 "passwrd":"1234" 20 } 21 } The line 3 in the previus example shws hw yu need t pass the X- 2Cmd X-Header. Line 4 specifies the Cntent Type required fr the POST cmmand. Als ntice that in this case the line 2 shws hw yu can use yur wn User-Agent header. The fllwing respnse shws a successful lgin actin and a sessin tken is included in the respnse. The HTTP headers are als included t shw the ASP.NET sessin returned by the server: 01 HTTP/ OK 02 Server: Micrsft-IIS/ Date: Fri, 02 Jan :52:51 GMT 04 X-Pwered-By: ASP.NET 05 Cnnectin: clse 06 X-AspNet-Versin: Set-Ckie: ASP.NET_SessinId=as0rpwf0llqsyvwc55rrl; path=/; HttpOnly 08 Cache-Cntrl: private 09 Cntent-Type: text/html 10 Cntent-Length: { 13 "header": { 14 "cmmand":"lgin", 15 "timestamp":new Date( ), 16 "errcde":0, 17 "errdesc":"", 18 "serverversin":" " 19 }, 20 "data": { 21 "tken":"1f4b5f33-d857-44e1-af65-d51baee2d325" 22 } 23 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 9 f 65

10 The fllwing respnse shws the case when there is a prblem with the user r Passwrd used t authenticate this sessin (ntice hw n HTTP headers are included frm this pint n): 01 { 02 "header": { 03 "cmmand":"lgin", 04 "timestamp":new Date( ), 05 "errcde":8863, 06 "errdesc":" address r Passwrd incrrect.", 07 "serverversin":" " 08 } 09 } The data sectin is nt included in the respnse sent by the server. When a JSON bject is null, yu can mit this field in the JSON string. Hwever, including it with an explicit null value is als a valid alternative. Fr example, the fllwing respnse is equivalent t the previus example: 01 { 02 "header": { 03 "cmmand":"lgin", 04 "timestamp":new Date( ), 05 "errcde":8863, 06 "errdesc":" address r Passwrd incrrect.", 07 "serverversin":" " 08 }, 09 "data": null 10 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 10 f 65

11 Authenticate Cmmand cde: authenticate The purpse f the authenticate cmmand is t authenticate the user and btain a sessin tken t be used in subsequent cmmands t cnsume the services prvided by the Secure Messaging platfrm. This cmmand requires an authrizatin key that was previusly btained using the lgin cmmand. The purpse f this cmmand is t allw third-party applicatins t seed the authenticatin passing the user credentials ( address and passwrd) nly nce in a cntrlled way and btain this authrizatin key than can then be stred lcally with the applicatin. Request parameters authkey This is the authrizatin key that yu previusly btained with the lgin cmmand. / Mandatry Respnse parameters tken This is the glbal unique identifier fr the sessin initiated with this Secure Messaging platfrm. The sessin tken is valid thrughut the length f the sessin initiated with the server and must be used with all subsequent cmmands. Sessins expire after a given amunt f time, at which time yu need t btain a new sessin tken. Sessin tkens can be used nly frm the remte lcatin frm where it was btained. Errr cdes Unexpected / Unknwn lgin errr. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 11 f 65

12 Examples In the fllwing example we assume the lgin cmmand had been called previusly and authrizatin key ( 519ac58c138e4d44568a989a4b33f47d ) was btained and cached: 01 POST /services/api.aspx HTTP/ User-Agent: 2client 03 X- 2Cmd: authenticate 04 Cntent-Type: applicatin/x-www-frm-urlencded; charset=utf-8 05 Hst: vmqa1: Cntent-Length: Expect: 100-cntinue 08 Cnnectin: Clse { 11 "header": { 12 "cmmand":"authenticate", 13 "timestamp":new Date( ), 14 "clientname":"apinettest", 15 "clientversin":" " 16 }, 17 "data": { 18 "authkey":"519ac58c138e4d44568a989a4b33f47d" 19 } 20 } At the time this cmmand was executed the authrizatin key was still valid and the fllwing respnse was btained frm the server with a valid sessin tken: 01 { 02 "header": { 03 "cmmand":"authenticate", 04 "timestamp":new Date( ), 05 "errcde":0, 06 "errdesc":"", 07 "serverversin":" " 08 }, 09 "data": { 10 "tken":"fdd6adfd-b0a5-58fd-a91e-188b2be00e12" 11 } 12 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 12 f 65

13 Frgt Passwrd Cmmand: frgtpasswrd The purpse f the frgtpasswrd cmmand is t initiate the prcess f recvering access t a Secure Accunt n behalf f the user. This cmmand sends the crrespnding user an ntificatin with a link t change their Passwrd. The user must be registered with the Secure Messaging platfrm in rder t wrk. Once the user clicks n the link, he r she is redirected t the Secure Messaging platfrm (Webmail) where they can chse a new Passwrd. This cmmand des nt require a sessin tken (it can be executed by any user.) Request parameters address / Mandatry Valid user Address. The address uniquely identifies the user in the Secure Messaging platfrm. The user must be registered with the Secure messaging platfrm in rder fr this cmmand t cmplete the peratin. Respnse parameters The frgtpasswrd cmmand des nt return a data sectin. Yu shuld check the header f the respnse t verify the actin was cmpleted successfully. See the Examples sectin fr mre details. Errr cdes Examples Unexpected / Unknwn frgtpasswrd errr. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm. The URL f the specified Secure Messaging platfrm didn t match any authrized platfrm Wrng request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) The Address prvided des nt exist in the Secure Messaging platfrm The specified user is nt registered with the Secure Messaging platfrm System cnfiguratin errr when creating the frgtpasswrd ntificatin. If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr sending ntificatin. If yu receive this errr cde please cntact supprt immediately. Because this cmmand des nt require authenticatin, there is n need t send the sessin tken r the Asp.Net sessin id as with the lgin cmmand. The fllwing example shws hw t initiate the frget passwrd wrkflw fr a test vmqa1:9999 PEN. The request must be sent t the Secure Messaging platfrm API URL and must cntain the X- 2Cmd X-Header parameter as shwn belw. Ntice that the bdy f the request has been frmatted fr readability purpses nly: Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 13 f 65

14 01 POST /services/api.aspx HTTP/ User-Agent: 2client 03 X- 2Cmd: frgtpasswrd 04 Cntent-Type: applicatin/x-www-frm-urlencded; charset=utf-8 05 Hst: vmqa1: Cntent-Length: Expect: 100-cntinue 08 Cnnectin: Clse { 11 "header": { 12 "cmmand":"frgtpasswrd", 13 "timestamp":new Date( ), 14 "clientname":"apinettest", 15 "clientversin":" " 16 }, 17 "data": { 18 " address":"user.tw@crp-natinal.cm" 19 } 20 } The line 3 in the previus example shws hw yu need t pass the X- 2Cmd X-Header. Line 4 specifies the Cntent Type required fr the POST cmmand. If the user s Address exists and is registered, the server will reply with the fllwing respnse: 01 HTTP/ OK 02 Server: Micrsft-IIS/ Date: Wed, 14 Jan :45:44 GMT 04 X-Pwered-By: ASP.NET 05 Cnnectin: clse 06 X-AspNet-Versin: Set-Ckie: ASP.NET_SessinId=yqdj2xfecyvk41bd4shwcbj; path=/; HttpOnly 08 Cache-Cntrl: private 09 Cntent-Type: text/html 10 Cntent-Length: { 13 "header": { 14 "cmmand":"frgtpasswrd", 15 "timestamp":new Date( ), 16 "errcde":0, 17 "errdesc":"", 18 "serverversin":" " 19 } 20 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 14 f 65

15 User / Member prvisining services The fllwing cmmands are available t prvisin new users in the crrespnding Secure Messaging platfrm r t retrieve and / r update the user prfile and their privileges. Security: Yu need a sessin tken t use these services. The infrmatin retrieved by these services depends n the privileges assigned t the user lgged in. T btain a sessin tken yu first need t call the Lgin cmmand. These fllwing cmmands are available in this sectin: Get Member Get the user s prfile. This cmmand may be used by any active user f the Secure Messaging platfrm. If it des nt have administrative privileges n the platfrm, the Get Member cmmand can be used nly t retrieve infrmatin abut the same user. Add Member Add a user t the Secure Messaging platfrm. This cmmand requires an administrative level user t use it. Depending n the requirements f the third party applicatin, the new user can autmatically be preregistered by the administratr. Update Member Update the user s infrmatin. This cmmand requires an administrative level user t use it. Get Members List* Retrieves the list f users with their basic status infrmatin. This cmmand requires an administrative level user t use it. Get Member Cmmand cde: getmember Use the getmember cmmand t retrieve the infrmatin assciated t a specified user identified by its Address. The infrmatin returned by this cmmand depends n the security level assigned t the user prvided t btain the sessin tken. Please refer t the Examples sectin belw fr the full syntax f the HTTP Request and Respnse. Request parameters address The Address that identifies the user yu are requesting infrmatin fr. / Mandatry Respnse parameters address status user s Address. The Address uniquely identifies the user in the Secure Messaging platfrm. The current status f the user in this Secure Messaging platfrm. Values: active, disable Inactive users cannt lgin t the Secure Messaging platfrm r use any f the services prvided by the API. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 15 f 65

16 created Datetime (UTC) Date and time the user was created in UTC / GMT frmat. package Object This is the User Grup the user is currently assigned t. The infrmatin prvided fr the User Grup includes the identifying guid and flag t indicate if the assignment is permanent r temprary and fr hw lng..guid This is the glbal unique identifier fr the User Grup..isTrial Blean Specifies if the User Grup assignment is in trial mde r nt..expiry Datetime (UTC) Specifies the date and time (UTC) this User Grup assignment will expire. This value is included nly if this is a temprary assignment (istrial is true). registratin Object Object specifying the registratin status f the user. If the user has nt registered, this attribute is null (r nt included in the respnse). If it s included in the respnse, it cntains tw prperties: status and timestamp. The status attribute has ne f the fllwing pssible values and the timestamp attribute indicates when that status was changed: started: The user has started the registratin prcess. pending: The user has submitted all the registratin infrmatin, but is waiting t cnfirm their address. cmpleted: The user cmpleted successfully the registratin prcess. pendingexpired: The user submitted the registratin infrmatin, but has nt cnfirmed the address. It is pssible the user has nt received the crrespnding cnfirmatin message. Example: "registratin": { "status": "cmpleted", "timestamp": new Date( ) } memberprfile Object Object specifying the attributes that define the user s prfile, including firstname and lastname. Other attributes supprted by the API are available t fully describe the new user in the system. Example: "memberprfile" : { "firstname": "Je", "lastname": "De" }.firstname First name f the user Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 16 f 65

17 .lastname Last name f the user extendedprfile List(Object) / Optinal This list prvides a flexible mechanism t extend the user s prfile with attributes that may nt crrespnd t specific Secure Messaging platfrm cncepts. Yu can use this list fr yur wn purpses, like fr string identifying keys that will link this user t an external system. Each item in the list cnsists f fur values: grup, key, type, and value. When yu create a new extended value yu must specify an identifying grup and name. This cmbinatin must be unique and the system has sme reserved grups that cannt be used by external systems via this API. The value attribute depends n the type f field specified. Yu have three alternatives: numeric: Numeric (integer) value. shrttext: Text value f 2,500 characters r less. Use this ptin when yu want t stre shrt descriptins r list items. lngtext: Free-frm text field with a maximum length f 10,000 characters. The cntent f this field is nt encrypted in the database. Yu have the ptin t encrypt the cntent f this attribute using yur wn mechanism and just passing a BASE64 string value in this field with type lngtext. Yu als have the ptin f passing just ne grup-name cmbinatin with a value cntaining an XML/JSON representatin f this extended prfile attribute. Example: "extendedprfile" : [ {"grup":"payment", "key":"userid", "type":"shrttext", "value":" "}, {"grup":"payment", "key":"amunt", "type":"numeric", "value":120}, {"grup":"payment", "key":"freq", "type":"shrttext", "value":"mnthly"} ] metricsusage List(Object) / Optinal List f metrics and usage tracked fr this user. Each metric usage has fur values: name, interval, limit, and usage. The name field identifies the metric; interval specifies the frequency the metric is enfrced and can be any f the fllwing values: Daily (D), Mnthly (M), and NInterval (I); the limit defines hw much f this metric is allwed t this user t use; and usage indicates hw much is currently used. The list f metrics, including their frequency and limit, is defined at the User Grup the user belngs t. Fr many f the metrics available the administratr can change the frequency f the metric fr a given User Grup t accmmdate specific needs. Als, the limit can be specified fr individual users verriding the User Grup definitin. The system keeps track f a series f metrics and mre are cnstantly added t the list. Currently, the supprted metrics are: friendinvites: Hw many invitatins available (n frequency abslute value). maxmessages: Hw many s the user can send per interval f time, e.g., daily. packageprmtins: Hw many available User Grup prmtins r spnsrships. Example: "metricsusage": [ {"name": "friendinvites", "limit": 10, "interval": "M", "usage": 5}, {"name": "maxmessages", "limit": 50, "interval": "D", "usage": 37}, {"name": "packageprmtins", "limit": 2, "interval": "I", "usage": 0} ] Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 17 f 65

18 Errr cdes Unexpected / Unknwn errr getting the user s prfile. If yu receive this errr cde please cntact supprt immediately Unknwn Secure messaging platfrm. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) System cnfiguratin errr retrieving the user s prfile. If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr: unknwn User Grup. The User Grup (package) assigned t the user des nt exist. If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr retrieving user metric. The metrics cannt be fund fr the specified user. If yu receive this errr cde please cntact supprt immediately Security errr. Yu d nt have enugh privileges t retrieve this user s prfile. Yu are always allwed t retrieve the prfile fr the same user used t acquire the sessin tken. If yu want t retrieve the prfile fr a different user, yu need t have administrative privileges. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 18 f 65

19 Examples The fllwing request attempts t retrieve the user s infrmatin: 01 { 02 "header": { 03 "cmmand":"getmember", 04 "timestamp":new Date( ), 05 "clientname":"apinettest", 06 "clientversin":" " 07 }, 08 "data":{ 09 " address":"user.tw@crp-natinal.cm" 10 } 11 } The respnse belw shws the User Tw user as an active user f the Secure Messaging platfrm: 01 { 02 "header": { 03 "cmmand":"getmember", 04 "timestamp":new Date( ), 05 "clientname":"apinettest", 06 "clientversin":" " 07 }, 08 "data":{ 09 " address":"user.tw@crp-natinal.cm", 10 "status":"active", 11 "created":new Date( ), 12 "package":{ 13 "istrial":true, 14 "expiry":new Date( ), 15 "guid":"c136ec82-d86f-4f6b-86b2-2b1a30035c28" 16 }, 17 "registratin":{ 18 "status":"cmpleted", 19 "timestamp":new Date( ) 20 }, 21 "memberprfile":{ 22 "firstname":"user", 23 "lastname":"tw" 24 }, 25 "metricsusage":[ 26 {"usage":1, "key":"friendinvites", "limit":5, "interval":"d"}, 27 {"usage":23, "key":"maxmessages", "limit":50, "interval":"d"}, 28 {"usage":0, "key":"packageprmtins", "limit":10, "interval":"i"} 29 ] 30 } 31 } In this example, the user is registered and has been temprarily assigned t a User Grup. The cmmand als includes the expiratin date fr this assignment. The user has 10 User Grup (package) prmtins / spnsrships available, can invite 4 mre users, and can send anther 27 secure messages fr that day. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 19 f 65

20 Add Member Cmmand cde: addmember Use the addmember cmmand t prvisin a new user in the crrespnding Secure Messaging platfrm. Creating a new user requires apprpriate privileges by the user used t btain a sessin tken. The new user can be created pre-registered, in which case yu prvide the apprpriate passwrd. Pre-registered users still need t cnfirm they wn the Address and will receive a ntificatin message fr that purpse. Request parameters address User s Address. The address uniquely identifies the user. / Mandatry status / Mandatry Values: active, disable This attribute cntrls if the user has access t the Secure Messaging platfrm. An active value enables the user t access the Secure Messaging platfrm services. When yu create a new user yu may want t use the disabled value t prvisin the new user but leaving it immediately disabled. preregister Specify if the user will be pre-registered r nt. Blean / Mandatry If yu pre-register the user yu need t prvide the passwrd and skipregcnfirmatin parameters. When yu pre-register a user yu must specify a passwrd fr this new user. Yu may ptinally als specify if the user shuld cmplete the standard registratin cnfirmatin prcedure using the skipregcnfirmatin parameter (default value is false). One pssible scenari where yu can take advantage f the skipregcnfirmatin parameter is if yur third party applicatin is ready t validate the new user withut requiring the final cnfirmatin. This is useful in cases where yu need t synchrnize users databases r when yu have enugh infrmatin t d the cnfirmatin fr the user (fr example, yu capture a credit card and are able t identify the user). If this is new user in bth systems is still recmmended t ask the user t cnfirm they wn the address specified. Fr that reasn the default value fr this parameter is false, meaning the registratin cnfirmatin prcess must be cmpleted. In this case, the user will receive an with a link they must click n, which will redirect them t the Secure Message Center (Webmail) when the final cnfirmatin is executed. Please ntice that registratin cnfirmatin messages expire after a given amunt f time cnfigured in the Web Admin Cnsle. Yu may need t trigger resending this if this is the case. passwrd skipregcnfirmatin Passwrd t lgin t the Secure Messaging platfrm. / Optinal This value is used nly if yu preregister the user. In this case, the field is mandatry. See preregister fr mre details. Blean / Optinal Default: false Skip the registratin cnfirmatin step. When this ptin is used, the user will be fully prvisined with their registratin already cnfirmed. This value is used nly if yu preregister the user. If nt specified the default value is false. See Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 20 f 65

21 preregister fr mre details. package Object / Optinal When yu create a new user yu have the ptin t specify a specific User Grup (package). If yu dn t specify a User Grup the system will assign the default value cnfigured in the Web Admin Cnsle. Yu d nt create new User Grups with this cmmand. The specified User Grup must already exist befre yu can use it. T assign a User Grup yu need t indicate three values: guid, istrial, and expiry date as explained belw. Yu identify the User Grup by its guid and indicate if this is a permanent r temprary assignment and fr hw lng. Example: "package": { "guid": "KSJDLASKDJASD", "istrial": false }.guid.istrial / Mandatry This is the glbal unique identifier fr the User Grup. Yu can btain the packageguid frm the Web Admin Cnsle. Yu may specify a specific User Grup GUID t be assigned t the new user. If yu dn t specify a User Grup (package), the default User Grup cnfigured in the Web Admin Cnsle fr new users will be used instead. If yu preregister the user, this value is verridden by the crrespnding value cnfigured in the Web Admin Cnsle. Specifies if the User Grup (package) assignment is in trial mde r nt. Blean / Mandatry When a User Grup is assigned in trial mde, yu must als specify the expiry date. When the expiratin time is cmpleted the system will autmatically reassign the user t the User Grup specified in the Web Admin Cnsle..expiry Specifies the date and time (UTC) this User Grup assignment will expire. This value is nt cnsidered if istrial is set t false. Datetime (UTC) / Optinal memberprfile Object / Mandatry Object specifying the attributes that define the user s prfile, including firstname and lastname. Other attributes supprted are available t fully describe the new user in the system..firstname.lastname First name f the user. Last name f the user. / Mandatry / Mandatry extendedprfile List(Object) / Optinal This list prvides a flexible mechanism t extend the user s prfile with attributes that may nt crrespnd t specific Secure Messaging platfrm cncepts. Yu can use this list fr yur wn purpses, like fr string identifying keys that will link this user t an external system. Each item in the list cnsists f fur values: grup, key, type, and value. When yu create a new extended value yu must specify an identifying grup and name. This cmbinatin must be unique and the system Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 21 f 65

22 has sme reserved grups that cannt be used by external systems via this API. The value attribute depends n the type f field specified. Yu have three alternatives: numeric: Numeric (integer) value. shrttext: Text value f 2,500 characters r less. Use this ptin when yu want t stre shrt descriptins r list items. lngtext: Free-frm text field with a maximum length f 10,000 characters. The cntent f this field is nt encrypted in the database. Yu have the ptin t encrypt the cntent f this attribute using yur wn mechanism and just passing a BASE64 string value in this field with type lngtext. Yu als have the ptin f passing just ne grup-name cmbinatin with a value cntaining an XML/JSON representatin f this extended prfile attribute. Example: "extendedprfile" : [ {"grup":"payment", "key":"userid", "type":"shrttext", "value":" "}, {"grup":"payment", "key":"amunt", "type":"numeric", "value":120}, {"grup":"payment", "key":"freq", "type":"shrttext", "value":"mnthly"} ] Respnse parameters status / Values: active, disable If the user is prvisined crrectly, the system will return the current status f the user. Errr cdes Unexpected / Unknwn errr creating the user s prfile. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) User already exists. The specified Address already exists. Use the updatemember cmmand t update the member s infrmatin System cnfiguratin errr creating the user recrd. If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr registering the user. Yu specified the user t be registered, but the server cannt cmplete the peratin. If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr sending ntificatin. The new user was created and registered successfully, but the welcme message failed t be delivered. Cnsider sending a new welcme message t this user Security errr. Yu d nt have enugh privileges t add a new user. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 22 f 65

23 Examples This fllwing request shws hw yu can create a new user. In this case we are attempting t add a new user withut pre-registratin and with the default User Grup cnfigured in the Web Admin Cnsle: 01 { 02 "header":{ 03 "cmmand":"addmember", 04 "timestamp":new Date( ), 05 "tken":"3110be81-786e-4ce1-bcea-18e935d5447c", 06 "clientname":"apinettest", 07 "clientversin":" " 08 }, 09 "data":{ 10 " address":"user.tw@crp-natinal.cm", 11 "status":"active", 12 "preregister":false", 13 "memberprfile":{ 14 "firstname":"qa", 15 "lastname":"tw" 16 } 17 } 18 } This sample respnse shws the case when the member already exists: 01 { 02 "header":{ 03 "cmmand":"addmember", 04 "timestamp":new Date( ), 05 "errcde": , 06 "errdesc":"member already exists!", 07 "serverversin":" " 08 } 09 } If it wrks, the user will receive this respnse: 01 { 02 "header":{ 03 "cmmand":"addmember", 04 "timestamp":new Date( ), 05 "errcde":0, 06 "errdesc":"", 07 "serverversin":" " 08 }, 09 "data":{ 10 "status":"active" 11 } 12 } In this case the user will receive the standard invitatin message specified in the Web Admin Cnsle. The fllwing example attempts t create a pre-registered user (where the passwrd is prvided): Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 23 f 65

24 01 { 02 "header":{ 03 "cmmand":"addmember", 04 "timestamp":new Date( ), 05 "tken":"3110be81-786e-4ce1-bcea-18e935d5447c", 06 "clientname":"apinettest", 07 "clientversin":" " 08 }, 09 "data":{ 10 " address":"user.tw@crp-natinal.cm", 11 "status":"active", 12 "preregister":true, 13 "passwrd":"1234", 14 "memberprfile":{ 15 "firstname":"user", 16 "lastname":"tw" 17 } 18 } 19 } In this case the user will receive a cnfirmatin message. The user will have t accept the link t activate the Secure Accunt. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 24 f 65

25 Update Member Use the updatemember cmmand t update a user s prfile. This cmmand requires administrative privileges. Cmmand cde: updatemember The user must already be registered befre using this cmmand. Yu must prvide the user s Address t identify the recrd yu want t update. Mst attributes are ptinal. Yu may specify nly the specific attributes yu want t change r all the user prfile values available if needed. Request parameters address Address that identifies the user in the Secure Messaging platfrm. / Mandatry Yu cannt change the address fr a user. The address specified in this field identifies the user yu want t update its infrmatin. status Yu may want t use the disabled value t temprarily disable the user. / Optinal Values: active, disable package Assign temprarily r permanently a new User Grup t this user. Object / Optinal Ntice that yu dn t create new User Grups with this cmmand. The specified User Grup must exist befre yu can use it. T assign a User Grup yu need t indicate three values: guid, istrial, and expiry date as explained belw. Yu identify the User Grup (package) by its guid and indicate if this is a permanent r temprary assignment and fr hw lng. Example: "package": { "guid": "KSJDLASKDJASD", "istrial": false }.guid.istrial / Mandatry This is the glbal unique identifier fr the User Grup. Yu can btain the packageguid frm the Web Admin Cnsle. Yu may specify a specific Package GUID t be assigned t the new user. If yu dn t specify a User Grup (package), the default User Grup cnfigured in the Web Admin Cnsle fr new users will be used instead. If yu preregister the user, this value is verridden by the crrespnding value cnfigured in the Web Admin Cnsle. Specifies if the User Grup assignment is in trial mde r nt. Blean / Mandatry When a User Grup is assigned in trial mde, yu must als specify the expiry date. When the expiratin time is cmpleted the system will autmatically reassign the user t the User Grup specified in the Web Admin Cnsle..expiry Specifies the date and time (UTC) this User Grup assignment will expire. Datetime (UTC) / Optinal Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 25 f 65

26 This value is nt cnsidered if istrial is set t false. memberprfile Object / Mandatry Object specifying the attributes that define the user s prfile, including firstname and lastname. Other attributes supprted are available t fully describe the new User..firstName / Optinal First name f the User.lastName / Optinal Last name f the User metrics List(Object) / Optinal Update the metric limits fr this User. Each metric has three values: name, interval, and limit. The name field identifies the metric and is mandatry; interval specifies the frequency the metric is enfrced and is an ptinal value that can be any f the fllwing: Daily (D), Mnthly (M), and NInterval (I); and the limit defines hw much f this metric is allwed t this user t use and is als an ptinal parameter. The list f metrics, including their frequency and limit, is defined at the User Grup the user belngs t. Fr many f the metrics available the administratr can change the frequency f the metric fr a given user t accmmdate specific needs. Als, the limit can be specified fr individual Users verriding the User Grup definitin. The system keeps track f a series f metrics and mre are cnstantly added t the list. Currently, the supprted metrics are: friendinvites: Hw many invitatins available (n frequency abslute value). maxmessages: Hw many s the user can send per interval f time, e.g., daily. packageprmtins: Hw many available User Grup prmtins r spnsrships. Example: "metrics": [ {"name": "friendinvites", "limit": 10, "interval": "M", "usage": 5}, {"name": "maxmessages", "limit": 50, "interval": "D", "usage": 37} ] extendedprfile List(Object) / Optinal This list prvides a flexible mechanism t extend the User s prfile with attributes that may nt crrespnd t specific Secure Messaging platfrm cncepts. Yu can use this list fr yur wn purpses, like fr string identifying keys that will link this user t an external system. Each item in the list cnsists f fur values: grup, key, type, and value. When yu create a new extended value yu must specify an identifying grup and name. This cmbinatin must be unique and the system has sme reserved grups that cannt be used by external systems via this API. The value attribute depends n the type f field specified. Yu have three alternatives: numeric: Numeric (integer) value. shrttext: Text value f 2,500 characters r less. Use this ptin when yu want t stre shrt descriptins r list items. lngtext: Free-frm text field with a maximum length f 10,000 characters. The cntent f this field is nt encrypted in the database. Yu have the ptin t encrypt the cntent f this attribute using yur wn mechanism and just passing a BASE64 string value in this field with type lngtext. Yu als have the ptin f passing just ne grup-name cmbinatin with a value cntaining an XML/JSON representatin f this extended prfile attribute. Example: Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 26 f 65

27 "extendedprfile": [ {"grup":"payment", "key":"userid", "type":"shrttext", "value":" "}, {"grup":"payment", "key":"amunt", "type":"numeric", "value":120}, {"grup":"payment", "key":"freq", "type":"shrttext", "value":"mnthly"} ] Respnse parameters status If the user is prvisined crrectly, the system will return the current status f the User. / Mandatry Values: active, disable Errr cdes Unhandled / Unknwn errr updating the User s prfile. Examples If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) Security errr. Yu d nt have enugh privileges t update this user s prfile System cnfiguratin errr retrieving the user s prfile. If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr retrieving the User Grup (package). If yu receive this errr cde please cntact supprt immediately System cnfiguratin errr updating the User Grup (package). If yu receive this errr cde please cntact supprt immediately Metric des nt exist. The specified User s metric des nt exist. The fllwing request shws hw a user can be updated t change the last name and assign a new metric t the user s prfile (in this case, t change the amunt f package prmtins available t the USer). This example als shws hw t use the extended prfile t save billing infrmatin. This billing infrmatin has n special meaning in the system, hwever, it can be used by third party applicatins fr their wn purpses. In this example, the credit card infrmatin (number) is sent encrypted (the Secure Messaging platfrm will nt knw hw t decrypt this infrmatin): Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 27 f 65

28 01 { 02 "header":{ 03 "cmmand":"updatemember", 04 "timestamp":new Date( ), 05 "tken":"3110be81-786e-4ce1-bcea-18e935d5447c", 06 "clientname":"apinettest", 07 "clientversin":" " 08 }, 09 "data":{ 10 " address":"user.tw@crp-natinal.cm", 11 "memberprfile":{ 12 "lastname":"tw" 13 }, 14 "extendedprfile": 15 [ 16 {"grup":"billing", "key":"cc-number", "type":"shrttext", "value":"sdfjwlksdulskdk239lks873=="}, 17 {"grup":"billing", "key":"cc-exp", "type":"shrttext", "value":"12/09"}, 18 {"grup":"billing", "key":"cc-name", "type":"shrttext", "value":"je De"}, 19 {"grup":"billing", "key":"cc-cde", "type":"shrttext", "value":"564"}, 20 {"grup":"billing", "key":"addr", "type":"shrttext", "value":"main Street 523, MA"}, 21 {"grup":"billing", "key":"freq", "type":"shrttext", "value":"mnthly"} 22 ], 23 "metrics": 24 [ 25 {"key":"friendinvites", "limit":5, "interval":"i"} 26 ] 27 } 28 } If the actin is allwed, the system will send this respnse: 01 { 02 "header":{ 03 "cmmand":"updatemember", 04 "timestamp":new Date( ), 05 "errcde":0, 06 "errdesc":"", 07 "serverversin":" " 08 }, 09 "data":{ 10 "status":"active" 11 } 12 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 28 f 65

29 Secure messaging services All these cmmands require a sessin tken and the infrmatin exchanged must belng t the authenticated user. Get Mailbx* Get Message Inf* Pre Create Message Save Message Send Message Get the full list f secure messages in a user s inbx. Requires a sessin tken. Get all secure message infrmatin related t a selected secure message. Requires a sessin tken. Creates a recrd in the database fr a secure message and prvides a glbal identifier (GUID) fr the new secure message t assciate cntent t it. Must happen befre a Save Message r Send Message cmmands. Requires a sessin tken. Save secure message s cntent t the prvided message identifier. Requires a valid and active message GUID. Requires a sessin tken. Cmpletes the transactin fr a secure message checking all business rules and privileges f the participants in the cnversatin and sends the ntificatin t the intended parties if it applies. Requires a valid and active message GUID. Requires a sessin tken. Add Attachments Send Bulk Message* Used t the send bulk secure messages t multiple recipients in ne peratin. The bulk-mailer cmmand supprts a flexible template language, which can be used t send persnalized secure messages t multiple users in ne actin. Optinally, this cmmand may include a pre-parsed cntent fr each user, allwing further custmizatin f the secure messages. Requires a sessin tken. Pre Create Message Cmmand cde: precreatemessage Use the precreatemessage cmmand t create a new secure message. If successful, the server will return the message glbal unique identifier (GUID) fr the new secure message alng with the list f default message ptins assciated t this message accrding t the privileges and attributes f the sender s prfile. The infrmatin returned by this cmmand depends n the security level assigned t the user prvided t btain the sessin tken. Please refer t the Examples sectin belw fr the full syntax f the HTTP Request and Respnse. Request parameters actin This attribute indicates the type f secure message t create. / Mandatry Values: newmessage, reply, replyall, frward The newmessage value creates a new message starting a new cnversatin, whereas the reply, replyall, and frward values indicate that this new secure message is part f an existing cnversatin, in which case yu als need t prvide the parentmsgguid parameter. Creating a newmessage requires that the User Grup assigned t the sender has the apprpriate privileges fr this actin. An apprpriate errr cde is prvided if the sender des nt have the apprpriate privileges. Cntinuing a cnversatin with a reply, replyall, r frward actin requires that the sender has the apprpriate privileges t create a new message and t assciate it t the parent message. This als depends n the privileges assigned t the parent message specified in parentmesgguid. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 29 f 65

30 parentmsgguid This is the Glbal Unique Identifier f the message yu are trying t link the message with. This parameter is mandatry fr the actin parameter values reply, replyall, and frward. / Optinal Respnse parameters msgguid This is the Glbal Unique Identifier (GUID) fr the new message. When yu start creating a new secure message by calling precreate cmmand yu will receive this msgguid identifier. Yu shuld stre this value fr the length f the transactin as it is used by all the remaining messaging cmmands that cmplete the infrmatin fr the new message. parentt parentcc pendefoptins The parentt parameter is a cmma-separated list f addresses and it is intended t be used in the TO field f the message s recipients list. This value is nrmally empty, but in sme ccasins and depending n the permissins f the user r their package attributes, the server will enfrce that the user sends this message t the specified list f addresses. In this case, an attempt t send the secure message t a different list f addresses may result in an errr when invking the savemessage cmmand. An example f this is the scenari when the User Grup frces users t cmmunicate exclusively with a pre-determined list f users. At this pint this parentt parameter is prvided nly as a reference fr client applicatins t alert the end user in the crrespnding user interface. The parentcc parameter is a cmma-separated list f addresses and it is intended t be used in the TO field f the message s recipients list. The same rules described fr parentt parameter apply t the parentcc parameter. List f Objects DEPRECATED This field is being deprecated. Please refrain frm using this field as a future release f the server will nt include this field anymre. This is the list f default message ptins supprted by the Secure Messaging Platfrm. These parameters are prvided s that client applicatins can infrm end users in the crrespnding user interface abut these message ptins and t be used as default values in the sendmessage cmmand if the user desn t specify values fr these ptins. These default values can be set by the administratr fr the entire Secure Messaging Platfrm. Each item in the list f default message ptins has a value and blcked attributes: value. The value attribute is a dynamic type parameter that indicates the default value t be used fr the crrespnding message ptin. Fr example, a blean value fr allwtracking indicates that the ptin can be enabled r nt (true/false). blcked. The blcked attribute is a hint t the client applicatin t cnfigure the user interface accrdingly t allw r disallw the end user changing the value f the specific message ptin. Fr example, the fllwing message ptin specificatin fr allwtracking indicates that when the savemessage cmmand is invked the message will be created with the d-nt-reply attribute: "allwtracking": { "value": false, "blcked": true } The blcked attribute is nly a hint fr the user interface. Client applicatins may still decide t ignre it and allw the end user t change the value even when it is indicated as blcked. Ding this may result n an Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 30 f 65

31 .allwreply.allwfrward.allwtracking.sharetracking apprpriate errr when invking the sendmessage cmmand. Belw it s the list f ptins currently supprted: Specifies if this secure message accepts reply actins. Specifies if this secure message accepts frward actin. Specifies if this secure message will have tracking available fr its recipients. Blean Blean Blean Blean Specifies if the sender f this secure message will be able t share tracking infrmatin with recipients. Errr cdes Unexpected / Unknwn errr creating the secure message. Examples If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm / Unknwn Sessin. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) Invalid secure message. An errr ccurred while validating the secure message ptins r user credentials ver this message. Yu may nt have enugh privileges t cmplete this actin r ne f the specific rules gverning User Grups may be preventing this actin Message set Fr Yur Eyes Only with Secure Accunt Passwrd. The parent message yu are replying/frwarding has been marked with Fr Yur Eyes Only with Secure Accunt Passwrd and the current sessin has nt unblcked access t the riginal message yet Message set Fr Yur Eyes Only with a Unique Passwrd. The parent message yu are replying/frwarding has been marked with Fr Yur Eyes Only with a Unique Passwrd and the current sessin has nt unblcked access t the riginal message yet This user des nt have access t this actin. The User Grup assigned t the user des nt allw sending new secure messages r reply/frward actin fr an existing message Cannt frward. The message yu are trying t frward des nt allw this actin. Yu may receive this errr when replying t a message and adding new recipients t the cnversatin. In this case the reply actin is cnsidered a frward actin Message terminated. The parent message yu are replying/frwarding has been terminated and access t it cannt be granted t cntinue the cnversatin Message recalled. The parent message yu are replying/frwarding has been recalled and access t it cannt be granted t cntinue the cnversatin. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 31 f 65

32 The fllwing request creates a secure message fr the user currently lgged in (determined by the sessin tken): 01 { 02 "header": { 03 "cmmand":"precreatemessage", 04 "tken": "9c885fa6-9b57-4c1f-89909", 05 "timestamp":new Date( ), 06 "clientname":"apinettest", 07 "clientversin":" " 08 }, 09 "data":{ 10 "actin": "newmessage" 11 } 12 } The respnse belw allws the actin and includes the message GUID alng with the list f default message ptins supprted: 01 { 02 "header": { 03 "cmmand":"precreatemessage", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data":{ 10 "msgguid": "23C9A222-1BE AF1E-15A D", 11 "parentt": "", 12 "parentcc": "", 13 "pendefoptins": { 14 "allwreply": { 15 "value": true, 16 "blcked": false 17 }, 18 "allwfrward": { 19 "value": true, 20 "blcked": false 21 }, 22 "allwtracking": { 23 "value": true, 24 "blcked": false 25 }, 26 "sharetracking": { 27 "value": true, 28 "blcked": false 29 }, 30 "freezedate": { 31 "value": new Date( ), 32 "blcked": false 33 } 34 } 35 } 36 } In this example the message is created successfully and its GUID is returned. The message des nt have an enfrced list f recipients and nne f the message ptins are blcked, meaning that the client applicatin may decide t ffer the end user the pssibility f setting these values when cmpleting the secure message. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 32 f 65

33 Save Message Use the savemessage cmmand t update the cntent and metadata f a secure message befre it is sent (cmpleted). Cmmand cde: savemessage Sme f the message infrmatin that yu can change with this cmmand includes: list f recipients, subject line, message bdy, message ptins, unique passwrd, and mre. All cntent / cnfiguratin parameters are ptinal, s yu may decide t change them individually r all at nce depending n the specific nature f yur client applicatin. When the call is successful, the server will return the current status f the message, which shuld be Draft status in mst cases, and the current list f message ptins assigned t this message. The server als returns ther indicatrs t be used in ptinal actins like adding new file attachments t the message and a flag t cnfirm which side will be in charge f ntifying the recipients f the new secure message. Please refer t the Examples sectin belw fr the full syntax f the HTTP Request and Respnse. Request parameters msgguid This is the Glbal Unique Identifier (GUID) fr the message being updated. / Mandatry When yu start creating a new secure message by calling precreatemessage cmmand yu will receive this msgguid identifier. Yu shuld stre this value fr the length f the transactin as it is used by all the remaining messaging cmmands that cmplete the infrmatin fr the new message. recipients This bject represents the list f recipients in the secure message. It may be cmprised f any f the TO:, CC:, and BCC: attributes (all ptinal). Each ne f these crrespnds t a cmma-separated list f addresses. Object / Optinal.t.cc.bcc / Optinal This is a cmma-separated list f addresses t be added t the TO: field in the secure message. / Optinal This is a cmma-separated list f addresses t be added t the CC: field in the secure message. / Optinal This is a cmma-separated list f addresses t be added t the BCC: field in the secure message. subject This is the subject line f the secure message. / Optinal bdy / Optinal This is the cntent f the secure message. The secure message s cntent may be in HTML r TEXT frmat accrding t the frmat parameter. The cntent f the bdy parameter must be stred encded in BASE64 frmat. frmat This is the frmat f the bdy f the secure message. / Optinal Values: HTML, TEXT Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 33 f 65

34 msgoptins List f values / Optinal This is the list f message ptins currently attached t this secure message. Each item in the list has a dynamic type value. Fr example, a blean value fr allwtracking indicates that the ptin can be enabled r nt (true/false). Belw is the current list f supprted message ptins. Sme f these ptins may nt be enabled and as such setting a value fr them may nt have an impact n the crrespnding message..allwreply Blean Specifies if this secure message accepts reply actins..allwfrward Blean Specifies if this secure message accepts frward actin..allwtracking Blean Specifies if this secure message will have tracking available fr its recipients..sharetracking Blean Specifies if the sender f this secure message will be able t share tracking infrmatin with recipients..fryureyesonlytype DEPRECATED This field is being deprecated. Please refrain frm using this field as a future release f the server will nt include this field anymre. Please use fyetype instead..fyetype Values: disabled, penpass, uniquepass The fyetype field indicates if the message was marked with the Fr Yur Eyes Only feature. The FYEO feature prvides an extra layer f security by allwing setting a passwrd fr each individual message that needs t be entered at the time f accessing the message. It can be ne f the fllwing values: disabled. The current message des nt use Fr Yur Eyes Only. uniquepass. The message has a unique passwrd assigned t it that needs t be prvided at the time the message is retrieved. penpass. In this case, the message des nt have a unique passwrd assigned t it, but the retriever needs t prvide their wn Service credentials in rder t access the cntent f the message. This is an intermediate slutin in which a message passwrd desn t need t be exchanged between the sender and recipients, but it asks fr cnfirmatin f each recipients credentials befre accessing the message. cracde / Optinal The cracde parameter crrespnds t the Challenge Respnse Authenticatin (CRA) feature that can be assigned t this message. When a user invites a new user and the CRA ptin is enabled in the Secure Messaging platfrm, they must assign a cde r passwrd that the new user must enter when registering. This can be set t the new user s custmer ID r PIN number assigned by yur rganizatin. validatedraft Blean / Optinal When true (default is false) this parameter indicates t the Server that it shuld enfrce the validatin rules t the draft message. The validatin rules are nrmally applied nly at the sendmessage cmmand (they are always applied at this pint). This flag is available s that client applicatins can prvide early feedback t end users abut the validity f the secure message withut having t send it yet. Respnse parameters Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 34 f 65

35 date Datetime (UTC) Date and time the message was created in UTC / GMT frmat. attachchunksize Numeric (Bytes) This value indicates the maximum file size (in Bytes) t be accepted by the Server when uplading attachments. If an attachment ges ver this limit, the client applicatin must split the file in chunks f this size. Uplading attachments in chunks f a pre-defined size allws client applicatins t better manage their resurces. They culd chse t implement a library where multiple chunks are upladed in parallel r sequentially depending n their unique requirements. msgoptins List f values / Optinal This is the list f message ptins currently attached t this secure message. Each item in the list has a dynamic type value. Fr example, a blean value fr allwtracking indicates that the ptin can be enabled r nt (true/false). Belw is the current list f supprted message ptins. Sme f these ptins may nt be enabled and as such setting a value fr them may nt have an impact n the crrespnding message..allwreply Blean Specifies if this secure message accepts reply actins..allwfrward Blean Specifies if this secure message accepts frward actin..allwtracking Blean Specifies if this secure message will have tracking available fr its recipients..sharetracking Blean Specifies if the sender f this secure message will be able t share tracking infrmatin with recipients..fryureyesonlytype DEPRECATED This field is being deprecated. Please refrain frm using this field as a future release f the server will nt include this field anymre. Please use fyetype instead..fyetype Values: disabled, penpass, uniquepass The fyetype field indicates if the message was marked with the Fr Yur Eyes Only feature. The FYEO feature prvides an extra layer f security by allwing setting a passwrd fr each individual message that needs t be entered at the time f accessing the message. It can be ne f the fllwing values: disabled. The current message des nt use Fr Yur Eyes Only. uniquepass. The message has a unique passwrd assigned t it that needs t be prvided at the time the message is retrieved. penpass. In this case, the message des nt have a unique passwrd assigned t it, but the retriever needs t prvide their wn Service credentials in rder t access the cntent f the message. This is an intermediate slutin in which a message passwrd desn t need t be exchanged between the sender and recipients, but it asks fr cnfirmatin f each recipients credentials befre accessing the message. e2k Object This is the uncmpressed versin f the Secure Message Signature (e2k) included in all ntificatins. A cmpressed versin f this key must be used by the client applicatin if it needs t send the ntificatins. When the server delivers the ntificatins, the client applicatin will receive the cmpressed versin f the e2k alng with the entire cntent f the ntificatin accrding t the templates in the Web Admin Cnsle. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 35 f 65

36 .hst.penguid.mailguid.parentmailguid Indicates the current URL fr the Secure Messaging platfrm. This is the Glbal Unique Identifier (GUID) fr the Secure Messaging platfrm. This is the Glbal Unique Identifier (GUID) fr the secure message. This is the Glbal Unique Identifier (GUID) fr the parent message if it exists. use 2smtpserver Blean This flag indicates if the server will deliver the ntificatins t the message recipients. When yu get a false value in this parameter yur client applicatin must take care f sending the ntificatin t the recipients. Currently, this is a VPS-wide setting. Errr cdes Unexpected / Unknwn errr creating the secure message. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm / Unknwn Sessin. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL r the sessin has expired Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) The message cannt be sent because the fllwing user(s) have blcked yu - <list f users> Yu may get this errr cde nly when using the validatedraft parameter This message cannt be sent because it cntains the fllwing blacklisted keywrds - <list f keywrds> Yu may get this errr cde nly when using the validatedraft parameter Yu dn't have privileges t invite new users t the Secure Messaging platfrm. Yu are inviting new users with this secure message and yur User Grup des nt allw yu t d that r yu d nt have enugh invites available. Yu may get this errr cde nly when using the validatedraft parameter CRA cde required t invite new user. Yu may get this errr cde nly when using the validatedraft parameter Yu cannt save draft n an invitatin messages. Invitatin messages d nt allw saving drafts The fllwing recipient(s) are nt allwed t receive secure messages - <list f users> Yu may get this errr cde nly when using the validatedraft parameter This user des nt have access t this actin. The User Grup assigned t the user des nt allw sending new secure messages r reply / frward actin fr an existing secure message. Yu may get this errr cde nly when using the validatedraft parameter Cannt frward. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 36 f 65

37 Examples The message yu are trying t frward des nt allw this actin. Yu may receive this errr when replying t a message and adding new recipients t the cnversatin. In this case the reply actin is cnsidered a frward actin. Yu may get this errr cde nly when using the validatedraft parameter Message terminated. The parent message yu are replying / frwarding has been terminated and access t it cannt be granted t cntinue the cnversatin. Yu may get this errr cde nly when using the validatedraft parameter Message recalled. The parent message yu are replying / frwarding has been recalled and access t it cannt be granted t cntinue the cnversatin. Yu may get this errr cde nly when using the validatedraft parameter. The fllwing request attempts t update a secure message passing user.tw@crp-natinal.cm in the TO: field f the recipients list. The subject line and the bdy f the message are als included in the request. The request als shws an example f hw t assign nn-default values t the message ptins. The validaredraft parameter is nt set t avid validatins (this is an peratin intended fr saving a draft f the message): 01 { 02 "header": { 03 "cmmand":"savemessage", 04 "tken": "9c885fa6-9b57-4c1f-89909", 05 "timestamp":new Date( ), 06 "clientname":"apinettest", 07 "clientversin":" " 08 }, 09 "data":{ 10 "msgguid": "23C9A222-1BE AF1E-15A D", 11 "recipients": { 12 "t": [ 13 "user.tw@crp-natinal.cm" 14 ] 15 }, 16 "bdy": "<html><bdy>this is the HTML cntent f the message</bdy></html>", 17 "subject": "Testing simple secure message", 18 "frmat": "HTML", 19 "msgoptins": { 20 "allwreply": true, 21 "allwfrward": true, 22 "allwtracking": true, 23 "sharetracking": false, 24 }, 25 "validatedraft": false 26 } 27 } The respnse belw allws the actin and includes the current status f the secure message alng with the list f message ptins currently assigned t this message. The e2k signature cmpnents list is als included in the respnse: Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 37 f 65

38 01 { 02 "header": { 03 "cmmand":"savemessage", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data":{ 10 "status": "DR", 11 "date": new Date( ), 12 "e2k": { 13 "hst": " 14 "penguid": "M909D15-XXXX-4C52-B00F-90009", 15 "mailguid": "ABCCCCC-XXXX-8IG3-B5C4-660E4A0B5014", 16 "parentmailguid": 0 17 }, 18 "attachchunksize": 4096, 19 "msgoptins": { 20 "allwreply": true, 21 "allwfrward": true, 22 "allwtracking": true, 23 "sharetracking": false, 24 "freezedate": new Date( ) 25 } 26 } 27 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 38 f 65

39 Add Attachments Cmmand cde: addattachments Use the addattachments cmmand t assign a new file attachment t the secure message. This cmmand is nt intended t uplad the actual files. Instead, client applicatins are expected t use this cmmand t declare their intentin f uplading a file at a future time. The recrd fr the file attachment is created in the system assciated t the given secure message and it is marked with status uplading. If there are n errrs, the Server will return the list f file attachments parts the client applicatin will need t uplad at a future time. This list includes the specific URLs fr where each attachment part needs t be upladed. Depending n the Web Admin Cnsle settings each file attachment may need t be divided int smaller parts and ptentially upladed t different File Servers. This architecture allws the system t handle large amunts f file transfers and ffers greater flexibility when scaling the system. Fr client applicatins wrking with the API, it ffers the pssibility f uplading multiple file attachment parts in parallel imprving the efficiency and reliability f these applicatins. Request parameters msgguid / Mandatry This is the Glbal Unique Identifier (GUID) f the secure message yu are adding file attachments t. When yu start creating a new secure message by calling precreatemessage cmmand yu will receive this msgguid identifier. Yu shuld stre this value fr the length f the transactin as it is used by all the remaining messaging cmmands that cmplete the infrmatin fr the new message. attachments.filename List(Object) / Mandatry Use this parameter t describe the file attachments t be assciated with the secure message. At least ne attachment must be included in the list. Fr each attachment, the minimum infrmatin t be included is the file name and size in bytes. Other ptinal and extensible parameters may be included with the request. The infrmatin fr each attachment must be described passing an instance f the inf attribute. The structure f this inf parameter is described belw: This is the actual file name in the file system f the file attachment file yu intend t uplad. / Mandatry This filename desn t need t be unique in the system. Each attachment file has a Glbal Unique Identifier (GUID) used t distinguish each file, s yu can uplad multiple cpies f the same file withut verriding previus cpies..size This is the size f the file in bytes. Numeric / Mandatry.extensins Object / Optinal The extensins parameter is a free-frm bject stred securely as-is. It is intended t be used by client applicatins fr their wn specific purpse. It allws string specific LOB (line f business) infrmatin t a file attachment that is relevant nly t the client applicatin making use f it. Fr example, it may be used t add an external r third party system identifier fr this file in the system t establish a relatinship with the external system. The cntent f this bject may even be encrypted with a prprietary mechanism knwn nly t the client applicatin prvider t further increase the cnfidentiality f sensitive infrmatin. The system will securely stre this infrmatin alng with all the meta-data assciated t the secure message. Given the inherent flexibility f this mechanism yur applicatin must be ready t deal with a dynamic list f attributes in this extensins parameter. This list f attributes may even be different fr each attachment. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 39 f 65

40 Respnse parameters chunksize attachmentparts Numeric (Bytes) This value indicates the maximum file size (in Bytes) t be accepted by the server when uplading file attachments. If an attachment ges ver this limit, the client applicatin must split the file in chunks f this chunksize size. Uplading attachments in chunks f a pre-defined size allws client applicatins t better manage their resurces. They culd chse t implement a library where multiple chunks are upladed in parallel r sequentially depending n their unique requirements. This value will have a value f zer 0 when n changes have been made t the chunksize already reprted in the savemessage cmmand. This is the list f file attachment parts that need t be upladed t the system. List(List(Object)) The first level f the list crrespnds t the attachment itself (as whle). Each ne f these is further divided int their specific parts accrding t the chunksize parameter. Fr each part the sequence number is returned in the attribute sequencenum alng with the uri where the file shuld be upladed. If yu receive mre than ne entry in the list f parts fr ne specific attachment yur client applicatin must split the file accrding t the chunksize parameter and uplad them with the crrespnding sequence number t the apprpriate lcatin..sequencenum This is the rder f this part r chunk in the whle file. This is a 0-based index f the attachment parts. Numeric.uri Specifies the full URL f where the file needs t be upladed using an HTTP POST actin. Blean The parameters in the URL grant sufficient permissins t the client applicatin t uplad the file directly t the specified File Server. Please ntice that this URL may be different fr each part. Errr cdes Unexpected / Unknwn errr creating the secure message. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm / Unknwn Sessin. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) The specified msgguid is nt valid fr the Secure Messaging platfrm General errr assciating the prvided file attachment9s) t the specified secure message. If yu receive this errr, please cntact supprt t prvide mre infrmatin. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 40 f 65

41 Examples The fllwing request adds a new file attachment t an existing secure message fr the user currently lgged in (determined by the sessin tken): 01 { 02 "header": { 03 "cmmand": "addattachments", 04 "tken": "9c885fa6-9b57-4c1f-89909", 05 "timestamp":new Date( ), 06 "clientname":"apinettest", 07 "clientversin":" " 08 }, 09 "data":{ 10 "msgguid": "23C9A222-1BE AF1E-15A D", 11 "attachments": [ 12 { 13 "inf": { 14 "filename": "lngsamplefile.exe", 15 "size": , 16 "extensins": { 17 "str-displayname": "lngsamplefile.exe" 18 }, 19 "type": "nrmal" 20 } 21 } 22 ] 23 } 24 } The respnse belw allws the actin including the list f file attachment parts the client applicatin will need t uplad: 01 { 02 "header": { 03 "cmmand": "addattachments", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data":{ 10 "chunksize": 0, 11 "attachmentparts": { 12 "d9d6713e-8e61-4efa-bc86-1c039d4edf2e": [ 13 { 14 "sequencenum": 0, 15 "uri": " A B1B-8D2AABA86AFE" 16 } 17 ] 18 } 19 } 20 } In this example the secure message is created successfully and its GUID is returned. The message des nt have an enfrced list f recipients and nne f the message ptins are blcked, meaning that the client applicatin may decide t ffer the end user the pssibility f setting these values when cmpleting the secure message. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 41 f 65

42 Send Message Cmmand cde: sendmessage Use the sendmessage cmmand t cmplete a secure message and initiate the ntificatin wrkflw fr the intended recipients. After this cmmand is executed n further mdificatins can be submitted t the secure message. Yu can, hwever, change its current status t further blck access t it if required; but yu cannt change identifying metadata fr this message anymre. The system executes a last check fr the validity f the peratin. Fr example, while the message was updated with ne r mre calls t cmmands like savemessage r addattachments, the client applicatin may have registered a specific list f recipients with this message. Hwever, nne f these recipients have actually been added t the system yet as it is in Draft state. Only at the time the message is sent are all the validatins executed. In particular, the system checks fr new users in the list f recipients and alerts the client applicatin with the apprpriate errr cdes. In this way, the system executes multiple types f validatins n the peratin t make sure that the rules defined in the Web Admin Cnsle and the privileges assigned t the User Grup f the user sending the message (identified implicitly by the sessin tken used t initiate the cmmand) lie within the expected parameters. If there are n errrs, the server will return a cnfirmatin fr the crrespnding ntificatin message that needs t be sent t the crrespnding recipients. The system prvides a SaaS SMTP Service and by default will deliver the ntificatins t the recipients s that client applicatins d nt need t wrry abut this actin. Hwever, sme clients may prefer t use their wn SMTP ntificatin implementatin r even alternative mechanism, in which case the system will return with the apprpriate infrmatin t ntify these users. In particular, the pre-ppulated cntent f the ntificatin in TEXT and HTML frmat is included in the respnse if it was cnfigured in the Web Admin Cnsle. The client applicatin can then directly ntify these users using a private mechanism. Request parameters msgguid This is the Glbal Unique Identifier (GUID) f the secure message yu are sending. / Mandatry When yu start creating a new secure message by calling precreatemessage cmmand yu will receive this msgguid identifier. Yu shuld stre this value fr the length f the transactin as it is used by all the remaining messaging cmmands that cmplete the infrmatin fr the new message. messagepasswrd cracde createnewmembers / Optinal Use the messagepasswrd parameter in cnjunctin with the uniquepass F.Y.E.O. message ptin. This passwrd crrespnds t the unique secret that needs t be knwn by the recipients when accessing the message. / Optinal The cracde parameter crrespnds t the Challenge Respnse Authenticatin (CRA) feature that can be assigned t this message. When a user invites a new user and the CRA ptin is enabled in the Secure Messaging platfrm, they must assign a cde r passwrd that the new user must enter when registering. This can be set t the new user s custmer ID r PIN number assigned by yur rganizatin. Blean / Mandatry Use this Blean parameter t specify if the system shuld autmatically invite new users that are included in the list f recipients f this message, but d nt exist in the system yet. If yu specify a false value fr this parameter the server will return an errr if the message includes new users in the list f recipients. This is an alternative and mre direct mechanism t prvisin new users. If yu are using this API yu may prefer t use the addmember cmmand t have greater cntrl ver the privileges and qutas the new user is being assigned t. Fr example, when yu prvisin a new user using the addmember cmmand yu can specify the User Grup this user shuld be assigned t, which gverns the privileges assigned t the new user. Using this methd yu can als by-pass ther restrictins that may be set at the Secure Messaging platfrm level like dmains that are nt allwed explicitly. Yu can als either assign a passwrd fr the new user r pre-register them in the system. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 42 f 65

43 When yu allw aut-prvisining new users with this parameter, all the default prvisining rules are used t determine if the peratin is valid. Fr example, des the sender user have enugh privileges t invite new users? Have all the invitatins allwed t a user being exhausted fr the current day? Is the dmain allwed? There are als rules that cntrl the autmatic assignment f the User Grup t the new user accrding t the Web Admin Cnsle settings. Allwing the creatin f new users in this autmatic way is prvided s that client applicatins may duplicate the functinality prvided in the native Secure Webmail applicatin that uses this same API t allw users t invite new users just by sending them a secure message. The recmmended wrkflw fr a client applicatin using this cmmand is t always pass a false value in this parameter and check fr the specific errr cde that ntifies that new members have been detected. Then, accrding t the specific requirements f the LOB implemented, the client applicatin may call the same cmmand again passing the true value in this parameter t allw the peratin. Respnse parameters use 2smtpserver This value indicates if the server sent the crrespnding ntificatins t the intended recipients. Blean If yu receive a true value in this parameter yu d nt need t d anything else. Hwever, if yu receive a false value in this parameter yur client applicatin must take care f sending the apprpriate ntificatin (r any ther ntificatin mechanism yur LOB applicatin may supprt). Currently the cnfiguratin t specify if the server shuld use the prvided SaaS slutin fr SMTP ntificatins is set at the Web Admin Cnsle level and cannt be verridden fr individual messages. Whether r nt yur client applicatin must send the ntificatins t the intended recipients, the server will return the cntent f such ntificatin in TEXT and/r HTML frmat accrding t the Web Admin Cnsle settings. The cntent f these ntificatins were created using the ntificatin templates cnfigured in the Web Admin Cnsle and were parsed with the individual infrmatin apprpriate fr this message. imbdyhtml This is the HTML cntent f the ntificatin message sent t the recipients f this secure message. Depending n the value f use 2smtpserver, the client applicatin must use this cntent and ntify the crrespnding recipients. If the use 2smtpserver is true, the client applicatin des nt need t send anther ntificatin message, althugh it may be required depending n the specific requirements f the LOB. This HTML message includes the cmpressed frmat fr the secure message key. imbdy This is the TEXT versin f the imbdyhtml utput parameter. Errr cdes Unexpected / Unknwn errr creating the secure message. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm / Unknwn Sessin. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL r the sessin has expired Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 43 f 65

44 The message cannt be sent because the fllwing user(s) have blcked yu - <list f users> This message cannt be sent because it cntains the fllwing banned keywrds - <list f keywrds> Yu dn't have privileges t invite new user. Yu are inviting new user with this message and yur User Grup des nt allw yu t d that r yu d nt have enugh invites available CRA cde required t invite new user Yu cannt save draft n an invitatin messages. Invitatin messages d nt allw saving drafts The fllwing recipient(s) are nt allwed t receive messages frm this Secure Messaging platfrm - <list f users> This user des nt have access t this actin. The User Grup assigned t the user des nt allw sending new secure messages r reply / frward actin fr an existing message Cannt frward. The message yu are trying t frward des nt allw this actin. Yu may receive this errr when replying t a message and adding new recipients t the cnversatin. In this case the reply actin is cnsidered a frward actin Message terminated. The parent message yu are replying / frwarding has been terminated and access t it cannt be granted t cntinue the cnversatin Message recalled. The parent message yu are replying / frwarding has been recalled and access t it cannt be granted t cntinue the cnversatin. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 44 f 65

45 Examples The fllwing cnfirms and sends a previusly created secure message fr the user currently lgged in (determined by the sessin tken). We allw aut-prvisining new users: 01 { 02 "header": { 03 "cmmand": "sendmessage", 04 "timestamp": new Date( ), 05 "tken": "9c885fa6-9b57-4c1f-89909", 06 "clientname": " 2.testapp", 07 "clientversin": "1.0" 08 }, 09 "data":{ 10 "msgguid": "23C9A222-1BE AF1E-15A D", 11 "createnewmembers": true 12 } 13 } The respnse belw allws the actin including the cntent fr the ntificatins that were sent ut t the recipients as well as the final indicatin that the server delivered the ntificatins: 01 { 02 "header": { 03 "cmmand": "sendmessage", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data":{ 10 "use 2smtpserver": true, 11 "imbdy": "*** 2 Private Netwrk ***\r\n\r\nqa TesterOne has sent yu a cnfidential message using 2 Private Netwrk.\r\n\r\nFllw the secure link belw t retrieve yur cnfidential message frm QA TesterOne:\r\n\r\nhttps://secure- messaging.cm/cde/web/?e=user.tw@crp-natinal.cm&mg=23c9a222-1be af1e- 15A D\r\n\r\n\r\n\r\nD nt reply t this ntificatin message. If yu d nt knw r trust User One (user.ne@crp-natinal.cm) r t unsubscribe please visit \r\n BEGIN 2 SIGNATURE \r\nvvr4+nsb3g70rznay5sypgw746lwqiwj7eqszpfa42tb6jyd0w/sna+2qfzljs\r\nl6fcamd+p5e8sb43zqgnq RYmMXLEUWarDifBHYjEzFhxHYJpgFKpCUdrZDe44wI\r\nL0Njg43cqvvu9eprYKGu8U7KztT4uffqUDPBpFUnZpiR +RjxAuONcVRy8y9Ia6\r\nuCXqFLcHb7ODWn9+3Q4j4+eEVVSjTs2ks7FYMlRaa8AJVsfcCpnvGV0/48vSFCNI\r\nu0B 6imODBY5HGZPxh7Ks2b0YR7S3t1wiZrOjUrxswCND7H4egCAUkGOd3gQvkUw6\r\nYFbWlpwNPdm20J+wOUS8KLYU5/vd 9few3IZ+2hRLnAykLvE6CXdh+0ygukjTrujv\r\nOuDR355r8b9n2zpHmX5SLiNFW9YYtjFJiahA3ymPFTxgYBAKyji qpoyznrohf\r\ntwnavvl2bdnqkuqkv5asww==\r\n END 2 SIGNATURE \r\n", Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 45 f 65

46 12 "imbdyhtml": "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitinal//EN\" \" style=\"fnt-family: Tahma, Arial, Helvetica, sans-serif;fnt-size:12px;width:700px;\">\r\n<h2>crp Natinal Secure Mail </h2>\r\n\r\n\t<p style=\"fnt-size:14px;\"> User One has sent yu a cnfidential message using Crp Natinal Secure Mail.</p>\r\n\r\n\t<p style=\"fntsize:14px;\"><strng>fllw the secure link belw t retrieve yur cnfidential message frm User One.</strng></p>\r\n\r\n <p style=\"fnt-size:14px;\"><strng><a href=\" 15A D\"> AF1E-15A D</a></strng></p>\r\n\r\n\t<br />\r\n\r\n\t<p style=\"clr:#ff0000;fntsize:10px;\">d nt reply t this ntificatin message. If yu d nt knw r trust QA TesterOne (qa-ne@ 2.cm) r t unsubscribe please visit /><hr><br />\r\n</div>\r\n\r\n<!--\r\n BEGIN 2 SIGNATURE \r\negljwtimflosqi3b2wtpk7ek8py7bdbkdhixvrqywd+mwpspxmqp8d0dghzdu\r\nia0tozevvdmknd1bhjydq yh30qimsyhyxasjant0ar2lxylydb74jnyt03l4gjc\r\nnsd8qmkfjru5hpowksyhnryx24qlt30q0p9/hvovxveqgi kyiikjp8k8xmmhxmx\r\nvrji6u3dlz4rtmith7ulyawztefnvxkrmdf7y1zyj1vxym5ru0khwsgkjt4bbr\r\nskk 0B4Twh5nwdIPC8fMpcDUH46fA8KJTQydl1fgqBqjETHAku7jBDu6O5LRbrlWb\r\nVlNBx7JiAfdW4h+vBFuxzuEPPiKR L2VKQRq2e13HrmHxR2trY2XNqP9BNZXIhYlK\r\n7aBMGwVmO3qcsqvbWyvxGvHKJdItJ77D8iCnBOALZNDIX25sT5iB 9sQcXOnirlH\r\nmYcllPE1RB+RenDOXTPj7w==\r\n END 2 SIGNATURE \r\n -->\r\n<!--\r\n(sent using SaaS SMTP Service) --></bdy>\r\n</html>" 13 } 14 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 46 f 65

47 Get Message List Cmmand cde: getmessagelist Use the getmessagelist cmmand t retrieve a list f secure messages sent r received by the user based n filters and srting criteria. The infrmatin fr each message returned by this cmmand is limited t nly the minimum identifying infrmatin. The idea is t btain a quick list f all the messages available and use ther cmmands (e.g., getmessagedetails) t btain mre specific infrmatin abut that message. Third party applicatin integratrs are encuraged t cache this list lcally and query the server t btain new messages n regular basis. The list f messages returned by this cmmand is limited t a page size cntrlled by the caller. Yu shuld iterate thrugh the message pages until yu have btained the cmplete list f messages. Request parameters pagenum respnsetype pagesize Numeric / Mandatry Use this value t chse which page t return based n the filters and srting applied. The amunt f message per page is cnfigured via the pagesize parameter. The pagenum value must be an integer value between 1 and the maximum number f pages accrding t the pagesize parameter. / Mandatry Values: idsonly, basic This value dictates the respnse returned t the client. We allw these ptins t bth return cleaner and mre succinct respnses as well as returning this infrmatin mre quickly and efficiently as fewer resurces are needed. Currently, these are the supprted values fr this : idsonly. Using the idsonly ptin will return nly the message guid fr all messages returned in the respnse. basic. When using the basic ptin mst metadata values are returned in the respnse excepting the full list f recipients and the bdy f the message. This ptin includes the date and time f when the message was sent and the subject f the message. Use this ptin when yu want t create a list f messages the user can access. Numeric / Mandatry The pagesize parameter dictates the size f the pages f the messages returned in the respnse. Please ntice that this value cannt be greater than 200. filter Use this parameter t describe the filter applied t the messages returned by this cmmand. Object / Optinal.grup Values: inbx, sent, draft, archive, trash This parameter is used t filter the returned messages based n which grup r flder these crrespnd t. Currently, the fllwing values are supprted: inbx. Use the inbx ptin t return nly messages that have been sent t yu. sent. Use the sent ptin t return nly messages that yu have sent. draft. Use the draft ptin t return messages that are still being edited. archive. Use the archive ptin t return messages that have been archived by the user. trash. Use the trash ptin t return messages that have been put in the trash by the user. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 47 f 65

48 srt.searchcriteria.type This parameter is used t filter the returned messages based n specific cntent in the message subject and the address f the sender r recipient. Nte: Messages are stred encrypted at rest n the server. As a result searches cannt be perfrmed n the cntent f the messages. Example: // Sent messages with subject cntaining the wrd test "filter": { "grup": "sent", "searchcriteria": "test" } Use this parameter t describe the srting applied t the messages returned by this cmmand. If this ptin is nt specified a default srt criteria is applied Object / Optinal Values: name, subject, date This parameter is used t chse which data field t use t srt the messages that are returned..directin This parameter is used t chse which directin t srt the messages. Example: // Srt messages by date in descending rder "srt": { "type": "date", "directin": "desc" } Values: asc, desc Respnse parameters The respnse is a list f messages. Hw much infrmatin is included fr each message in the list depends n the value passed t the respnsetype parameter in the request. Belw is included the descriptin f all the fields that may cme back in the respnse fr each message. messages List(Object) List f messages matching the criteria in the request. Each message will cntain the identifier (guid) and depending n the respnsetype it will als include the remaining fields..guid The guid is a glbal unique identifier fr the message. Available with all values f respnsetype..recipients List(Object) The recipients field is a list f all the recipients in the message. This field is available nly with the basic value fr respnsetype, and when the filter field is equals t sent in the input parameters. Each recipient cntains the fllwing attributes: . This is the address f the recipient. field. This is the field in which the recipient appears in the message header. It can be ne f the Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 48 f 65

49 fllwing values: t. The TO field f the message. cc. The Cc field f the message. bcc. Bcc field f the message. firstname. The first name f the recipient. lastname. The recipient s last name. Please ntice that the name f the recipient is btained frm the live user s prfile. That means that if yu call this service a secnd time yu may get a different value fr the recipient s name if the crrespnding user prfile is changed..sender.subject.methd The sender field is the riginal sender f the message. This field is returned with all values f the respnsetype parameter. Each sender cntains the fllwing attributes: . This is the address f the sender. firstname. The first name f the sender. lastname. The sender s last name. Object The subject field crrespnds t the message s subject line. This field is available nly with the basic value fr respnsetype. Values: received, sent The methd field describes the access type yu have t this message. If yu are the sender f the message yu will have sent access, whereas if yu have received the message as ne f the recipients r anther delegated methd yu will have the received access. The access methd als cntrls the level f infrmatin returned fr each message. This field is returned with all values f the respnsetype parameter..date The date field crrespnds t the date and time the message was sent. Datetime (UTC).status.hasAttachments Values: pending, active, recalled, upladingattachments, draft The status field indicates the current status f the message. This field is returned with all values f the respnsetype parameter and it can be ne f the fllwing values: pending. The message has nt been delivered yet. Typical scenaris include a message has just been created r it is waiting fr attachments t be upladed prir t send the ntificatin, but n ther cntent infrmatin has been prvided. active. The message was delivered and it s currently available t the sender and all authrized recipients. recalled. The sender f the message has recalled this message and is n lnger available t the recipients f this message (it is still available t the sender) upladingattachments. The client applicatin has started uplading attachments, but has nt cmpleted the peratin yet. draft. The message has nt been sent yet and it cntains draft infrmatin submitted earlier. Blean This Blean value is based n the message cntaining attachments r nt. This field is available nly with the basic value fr respnsetype. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 49 f 65

50 .hasvide Blean This Blean value is based n the message cntaining a vide message r nt. This field is available nly with the basic value fr respnsetype..isretrieved Blean This Blean value indicates if the user crrespnding t the sessin issuing this cmmand has retrieved the message r nt. This field is available nly with the basic value fr respnsetype. Use this field t identify unread messages. Please ntice that if a message has been read by the user f the current sessin, it desn t mean that ther recipients have als retrieved it. Fr mre details abut the retrieval status please see the tracking cmmands..fyetype Values: disabled, penpass, uniquepass The fyetype field indicates if the message was marked with the Fr Yur Eyes Only feature. The FYEO feature prvides an extra layer f security by allwing setting a passwrd fr each individual message that needs t be entered at the time f accessing the message. This field is available nly with the basic value fr respnsetype and it can be ne f the fllwing values: disabled. The current message des nt use Fr Yur Eyes Only. uniquepass. The message has a unique passwrd assigned t it that needs t be prvided at the time the message is retrieved. penpass. In this case, the message des nt have a unique passwrd assigned t it, but the retriever needs t prvide their wn Service credentials in rder t access the cntent f the message. This is an intermediate slutin in which a message passwrd desn t need t be exchanged between the sender and recipients, but it asks fr cnfirmatin f each recipients credentials befre accessing the message. Errr cdes Unexpected / Unknwn errr retrieving the message list. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm / Unknwn Sessin. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL r the sessin has expired Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) General errr retrieving the message list data. If yu receive this errr, please cntact supprt t prvide mre infrmatin General errr retrieving specific data fr a specific message. If yu receive this errr, please cntact supprt t prvide mre infrmatin General errr retrieving specific state data fr a message. If yu receive this errr, please cntact supprt t prvide mre infrmatin General errr retrieving specific methd data fr a message. If yu receive this errr, please cntact supprt t prvide mre infrmatin. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 50 f 65

51 Examples The fllwing example btains the 3 mst recent messages in the Inbx, including the sender s name: 01 { 02 "header": { 03 "cmmand": "getmessagelist", 04 "timestamp": new Date( ), 05 "tken": "9c885fa6-9b57-4c1f-89909", 06 "clientname": " 2.testapp", 07 "clientversin": "1.0" 08 }, 09 "data":{ 10 "pagenum":1, 11 "respnsetype":"basic", 12 "pagesize":4, 13 "filter":{ 14 "grup":"inbx" 15 }, 16 "srt":{ 17 "type":"date", 18 "directin":"desc" 19 } 20 } 21 } The respnse includes sme basic infrmatin fr each message, but mre imprtantly, it cntains the unique identifier (GUID) fr each message in the list. The client applicatin shuld cache this list and query the server fr details abut each message r fr tracking infrmatin: 01 { 02 "header": { 03 "cmmand": "getmessagelist", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data":{ 10 "messages":[ 11 { 12 "guid":"a5c919c a d2ecaa8c9", 13 "subject":"testing secure message with attachments", 14 "sender":{ 15 " ":"user.ne@crp-natinal.cm", 16 "firstname":"user", 17 "lastname":"one" 18 }, 19 "date":new Date( ), 20 "hasattachments":true, 21 "hasvide":false, 22 "isretrieved":true, 23 "status":"active", 24 "methd":"received", 25 "fyetype":"disabled" 26 }, 27 { 28 "guid":"7f d5-4ea a14e404eda4", 29 "subject":"testing simple secure message", 30 "sender":{ 31 " ":"user.ne@crp-natinal.cm", 32 "firstname":"user", 33 "lastname":"one" 34 }, 35 "date":new Date( ), 36 "hasattachments":false, Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 51 f 65

52 37 "hasvide":false, 38 "isretrieved":false, 39 "status":"active", 40 "methd":"received", 41 "fyetype":"disabled" 42 }, 43 { 44 "guid":"932497d2-89e f-8e9810c4046f", 45 "subject":"simple 2", 46 "sender":{ 47 " ":"user.tw@crp-natinal.cm", 48 "firstname":"user", 49 "lastname":"tw" 50 }, 51 "date":new Date( ), 52 "hasattachments":false, 53 "hasvide":false, 54 "isretrieved":true, 55 "status":"active", 56 "methd":"received", 57 "fyetype":"disabled" 58 } 59 ] 60 } 61 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 52 f 65

53 Get Message Details Cmmand cde: getmessagedetails Use the getmessagedetails cmmand t retrieve the details f a message. The cntent available in the respnse depends n the permissins assigned t the user fr this particular message. The user retrieving the message must specify the glbal unique identifier f the message, the detail level f the infrmatin returned, plus an ptinal unique passwrd if required, and will btain all the metadata available fr that message, plus the cntent if requested and available t the user. Request parameters guid / Mandatry Glbal unique identifier f the message. Yu receive this guid fr each message when yu get the list f messages fr the current sessin. messagepasswrd Use the messagepasswrd parameter when yu knw the message has been marked t use Fr Yur Eyes Only (F.Y.E.O.) feature. If the message requires F.Y.E.O. yu must prvide the unique passwrd fr the message if the fyetype attribute f that message is uniquepass, therwise if the fyetype is penpass the user s passwrd fr the service must be prvided in this parameter. respnsetype / Mandatry Values: metadata, full This value dictates the respnse returned t the client. The fllwing values are supprted: includeextensins full. All infrmatin available fr this message is returned t the caller accrding t the privileges granted t the current sessin s user ver the message identified by the guid parameter. metadata. This ptin returns all the infrmatin available assciated t this message except fr the actual cntent f the message (the bdy respnse field). Use this ptin when yu have already retrieved the message in a previus sessin and want t refresh the related infrmatin r fr cases where yu want t btain as much infrmatin available fr a particular message withut marking it as retrieved in tracking. The current user desn t need full access t the message t access its metadata. Blean Default: false This Blean value indicates if message extensins shuld be included in the respnse fr the specified message. Each message can be assigned an arbitrary list f key-value pairs. The system uses sme f these extensins t add extended infrmatin fr each message that is relevant t the internal f the system. Fr example, the system uses this feature t stre the draft list f recipients f the message as part f the native client applicatins. Yur applicatin may r may nt assign prprietary sensitive infrmatin t this field and as such each thirdparty applicatin prvider shuld evaluate making this infrmatin available as part f the metadata f the message r under full access nly. Fr example, third-party integratrs wrking with Secure Frms shuld use includeextensins = true when retrieving the full cntent f the message t retrieve the data fr the secure frm pst. The system uses the jsn-cntacttag message extensin t stre encrypted the cntent f the secure frm pst. Respnse parameters guid Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 53 f 65

54 Glbal unique identifier f the message. status creatindate frm subject bdy isretrieved parentguid cmpseactin frmat Values: pending, active, recalled, draft The status field indicates the current status f the message. This field is returned with all values f the respnsetype parameter and it can be ne f the fllwing values: pending. The message has nt been delivered yet. Typical scenaris include a message has just been created r it is waiting fr attachments t be upladed prir t send the ntificatin, but n ther cntent infrmatin has been prvided. active. The message was delivered and it s currently available t the sender and all authrized recipients. recalled. The sender f the message has recalled this message and is n lnger available t the recipients f this message (it is still available t the sender) draft. The message has nt been sent yet and it cntains draft infrmatin submitted earlier. The creatindate field indicates the date and time the message was created. The frm field is the riginal sender f the message and it is cmprised f the fllwing attributes: . This is the address f the sender. firstname. The first name f the sender. lastname. The sender s last name. Datetime (UTC) Object The subject field crrespnds t the message s subject line. This field is available nly with the basic value fr respnsetype. This is the cntent f the message. The message bdy may be in either text r html frmat. Use the frmat field t determine hw t use the bdy field. Blean This Blean value indicates if the user crrespnding t the sessin issuing this cmmand has retrieved the message r nt. Please nte that if yu use the full value fr the respnsetype request parameter the message will be autmatically marked as retrieved by the user crrespnding t the current sessin. This is the message GUID crrespnding t the parent message in a reply/frward scenari. If this is a new message this field will be empty (r nt present) Values: newmessage, reply, replyall, frward The cmpseactin field indicates the riginal peratin that created this secure message. The available values are: newmessage. This value indicates the message is a new message and has n relatinship with previus messages. reply. This value indicates that this message was created in respnse t a reply cmmand. replyall. Similar t the reply case, but in respnse t a Reply All scenari. frward. Similar t the previus case, but in respnse t a Frward scenari. Values: text, html Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 54 f 65

55 extensins ptins The frmat specifies the frmat f the message and it cntrls hw t interpret the bdy field f the message. It can have tw values: html. The cntent f the message is in HTML frmat and shuld be handled accrdingly. text. The cntent f the message is in TEXT frmat and shuld be handled accrdingly. List(KeyValuePair) The extensins field cntains a variable list f key-value pairs used by the system and third-party integratrs t extend the functinality supprted by each message. The key and value members must be f value. Nte fr C# develpers: This key-value pairs list match the C# type Dictinary<string,string> Each message may cntain a different number f extensins depending n the cntext in which the message was created. The system makes use f the fllwing keywrds: draft-t, draft-cc, draft-bcc. Used by the Webmail and Mbile applicatins. It cntains the list f TO, CC, and BCC recipients fr a message while in cmpse mde. ntificatin list. List f ntificatin addresses used by the system when sending ntificatins fr a secure message. jsn-cntacttag. This is a serialized JSON string which cntains the infrmatin assciated t a secure frm pst. If a message cntains this key in the extensins list the message crrespnds t a secure frm submissin. The deserialized JSON value has the fllwing structure: . The address f the user submitting the secure frm. This is an ptinal feature supprted by secure frms that allw the native client applicatins like the Webmail client and the Outlk Tlbar t use this address when the recipient f the secure frm pst replies t the message, s that the respnse is directed autmatically t the intended persn that submitted the secure frm and nt the system s address frm where the ntificatin was delivered. items. This is anther key-value pair list with all the INPUT fields included in the POST actin f the secure frm pst. The cntent f this list depends cmpletely n the design used by the client fr their secure frm. This is the list f message ptins currently attached t this secure message. List f values / Optinal Each item in the list has a dynamic type value. Fr example, a blean value fr allwtracking indicates that the ptin can be enabled r nt (true/false). Belw is the current list f supprted message ptins. Sme f these ptins may nt be enabled and as such setting a value fr them may nt have an impact n the crrespnding message..allwreply.allwfrward.allwtracking Specifies if this secure message accepts reply actins. Specifies if this secure message accepts frward actin. Specifies if this secure message will have tracking available fr its recipients. Blean Blean Blean.shareTracking.frYurEyesOnlyType.fyeType Specifies if the sender f this secure message will be able t share tracking infrmatin with recipients. Blean DEPRECATED This field is being deprecated. Please refrain frm using this field as a future release f the server will nt include this field anymre. Please use fyetype instead. Values: disabled, penpass, uniquepass Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 55 f 65

56 The fyetype field indicates if the message was marked with the Fr Yur Eyes Only feature. The FYEO feature prvides an extra layer f security by allwing setting a passwrd fr each individual message that needs t be entered at the time f accessing the message. It can be ne f the fllwing values: disabled. The current message des nt use Fr Yur Eyes Only. uniquepass. The message has a unique passwrd assigned t it that needs t be prvided at the time the message is retrieved. penpass. In this case, the message des nt have a unique passwrd assigned t it, but the retriever needs t prvide their wn Service credentials in rder t access the cntent f the message. This is an intermediate slutin in which a message passwrd desn t need t be exchanged between the sender and recipients, but it asks fr cnfirmatin f each recipients credentials befre accessing the message. attachments List(Object) This is the list f file attachments assciated t this secure message. Each item in the list represents an instance f an attachment bject. Belw is the descriptin f each attachment field..guid The guid field is a glbal unique identifier fr this attachment. It is used t identify this attachment in next peratins, like retrieving the attachment..status Values: wait, uplad, active, cancel, deleted, recalled The status field specifies the current status f this attachment. These are the values currently supprted:. The attachment specificatin was created in the system, but n parts f the file have been upladed yet. uplad. The file attachment is currently being upladed. active. All attachment parts have been upladed successfully. The attachment is nw available t be dwnladed by apprved users. cancel. The attachment was declared as part f the message, but the uplad actin was cancelled. deleted. The attachment was deleted by its wner. recalled. The attachment was recalled by the wner. This means that the attachment is still available t the wner, but recipients f the message where this attachment was included n lnger have access t it..filename The file name f the attachment.filesize Numeric The file size f the attachment in bytes..partcunt Numeric The number f parts the file attachments has been split n. By default the system splits each file attachments in chunks f 4MB..upladedBy This is the riginal wner f this attachment..upladdate Datetime (UTC) This is the date and time when this attachment was upladed..extendedprperties Object / Optinal The extendedprperties field is a free-frm bject stred securely as-is. It is intended t be used by client applicatins fr their wn specific purpse. It allws string specific LOB (line f business) infrmatin t a file attachment that is relevant nly t the client applicatin making use f it. Fr example, it may be used t Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 56 f 65

57 add an external r third party system identifier fr this file in the system t establish a relatinship with the external system. The cntent f this bject may even be encrypted with a prprietary mechanism knwn nly t the client applicatin prvider t further increase the cnfidentiality f sensitive infrmatin. The system will securely stre this infrmatin alng with all the meta-data assciated t the secure message. Given the inherent flexibility f this mechanism yur applicatin must be ready t deal with a dynamic list f attributes in this field. This list f attributes may even be different fr each attachment. Errr cdes Unexpected / Unknwn errr retrieving the message list. If yu receive this errr cde please cntact supprt immediately Unknwn Secure Messaging platfrm / Unknwn Sessin. The sessin tken was assigned t a different Secure Messaging platfrm than the specified URL r the sessin has expired Wrng Request frmat. This is a valid JSON bject, but the request has an invalid frmat. Yu may receive this message when yu d nt include mandatry fields r assigned an invalid value t ne f the fields (e.g., wrng data type) General errr validating the message. One r mre f the validatin rules t access a message were nt met. Typical scenaris include user credentials d nt allw the actin ver the specified message, the message desn t exist. Fr mre details, please cntact Supprt t prvide mre infrmatin Validatin access check failed: Message recalled. The message has been marked as recalled and the current user is nt the wner f the message Validatin access check failed: Message is F.Y.E.O. and sessin credentials are invalid Validatin access check failed: Message is F.Y.E.O. and unique passwrd was nt prvided. Examples The fllwing example retrieves the metadata infrmatin fr a message fr which the current user is a valid recipient: 01 { 02 "header": { 03 "cmmand": "getmessagedetails", 04 "timestamp": new Date( ), 05 "tken": "9c885fa6-9b57-4c1f-89909", 06 "clientname": " 2.testapp", 07 "clientversin": "1.0" 08 }, 09 "data":{ 10 "guid":"2e68c c-4c8f-92d3-1068fe1821f1", 11 "respnsetype":"metadata" 12 } 13 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 57 f 65

58 The respnse indicates the message is valid and all the access validatin rules were satisfied. In this case the message cntains tw attachments and has nt been retrieved yet by the caller. The message als indicates that it was a new message (nt a reply r frward actin) and has nly ne recipient. The respnse als includes the message ptins allwed fr this message. 01 { 02 "header": { 03 "cmmand": "getmessagedetails", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data":{ 10 "guid":"2e68c c-4c8f-92d3-1068fe1821f1", 11 "status":"active", 12 "creatindate":new Date( ), 13 "frm":{ 14 " ":"user.ne@crp-natinal.cm", 15 "firstname":"user", 16 "lastname":"one" 17 }, 18 "subject":"testing secure message with attachments", 19 "isretrieved":false, 20 "hiddenrecipients":false, 21 "cmpseactin":"newmessage", 22 "frmat":"html", 23 "recipients":[ 24 { 25 "field":"t", 26 " ":"user.tw@crp-natinal.cm", 27 "firstname":"user", 28 "lastname":"tw" 29 } 30 ], 31 "ptins":{ 32 "allwreply":true, 33 "allwfrward":true, 34 "allwtracking":true, 35 "sharetracking":true, 36 "fyetype":"disabled" 37 }, 38 "attachments":[ 39 { 40 "guid":"6943bd7b-def8-43ee-88fd-8323cf09564f", 41 "status":"active", 42 "filename":"cpy f ap_trans.xlsx", 43 "filesize":30044, 44 "partcunt":1, 45 "upladedby":"user.ne@crp-natinal.cm", 46 "upladdate":new Date( ), 47 "extendedprperties":{ } 50 }, 51 { 52 "guid":"e d-d7ed5e6a1212", 53 "status":"active", 54 "filename":"cpy f ap_trans3.xlsx", 55 "filesize":23397, 56 "partcunt":1, 57 "upladedby":"user.ne@crp-natinal.cm", 58 "upladdate":new Date( ), 59 "extendedprperties":{ } 62 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 58 f 65

59 63 ] 64 } 65 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 59 f 65

60 Delete Message Cmmand cde: deletemessage Use the deletemessage cmmand t remve a message frm the list f active messages. Deleting a message nly hides its cntent frm active lists. Fr auditability purpses messages cannt be deleted frm the system. They get mved t a deleted state where the message is n lnger available by any f the participants f that message. In rder t issue this cmmand, the current sessin s user prfile must have enugh privileges t invke this feature. Request parameters guids Glbal unique identifier f the messages that yu need t delete. List() / Mandatry Yu receive this guid fr each message when yu get the list f messages fr the current sessin. Respnse parameters This cmmand des nt return any data sectin, nly the cntent f the header sectin f the respnse. Errr cdes Examples Unexpected / Unknwn errr deleting a message. If yu receive this errr cde please cntact supprt immediately. An unexpected/unhandled errr was raised after executing this cmmand Wrng Request frmat. The frmat f the request is nt supprted by the server r the request data is missing Wrng Request frmat. Missing list f messages t delete. This is a valid JSON request, but there are n message GUIDs specified with the peratin There was a prblem deleting secure message. Please try again. There was a prblem with the delete peratin. One r mre f the specified message GUIDs d nt exist r yu d nt have privileges t delete the specified messages. The fllwing example attempts t delete ne message given the message s GUID: 01 { 02 "header": { 03 "cmmand": "deletemessage", 04 "timestamp": new Date( ), 05 "tken": "9c885fa6-9b57-4c1f-89909", 06 "clientname": " 2.testapp", 07 "clientversin": "1.0" 08 }, 09 "data":{ 10 "guids":[ 11 "944C446F-D2C FFF-6C D" 12 ] 13 } 14 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 60 f 65

61 The respnse includes and errr cde and errr descriptin as a result f the peratin. In this case, the respnse indicates the peratin succeeded: 01 { 02 "header": { 03 "cmmand": "deletemessage", 04 "timestamp": new Date( ), 05 "errcde": 0, 06 "errdesc": "", 07 "serverversin": " " 08 }, 09 "data": { 10 } 11 } Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 61 f 65

62 Appendix: 2 JSON Data Types This is the list f data types supprted by the parameters included in the request / respnse bjects. The API s request / respnse JSON bjects fllw the specificatin described belw. Fr a general descriptin f the JSON specificatin, see A string is a cllectin f zer r mre Unicde characters, wrapped in duble qutes, using backslash escapes: A character is represented as a single character string. A string is very much like a C r Java string. Example: "firstname" : "Jhn", "descriptin" : "This is a \"descriptin\" using the escape sequence" Number A number is very much like a C r Java number. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 62 f 65

63 Example: "age" : 4, "salary" : Blean Blean values are specified by the wrds true and false. Example: "usedefault" : true DateTime In the API, date time values crrespnd t a standard JavaScript Date cnstructr. The parameter fr the cnstructr is an integer that represents the number f millisecnds since 01/01/70 00:00:00. Unless specified therwise, all cmmands in the API stre dates in GMT frmat. Yu must d the apprpriate cnversin frm yur lcal time zne when setting/retrieving date time parameters. A sample implementatin f hw t calculate the millisecnds value in C# will be like this: lng val = (datetime.ticks - (new DateTime(1970, 1, 1)).Ticks) / (lng)10000; The example belw crrespnds t January 6th 2009, 5:17:45 AM GMT, which is the same than January 5th 2009, 9:17:45 PM PST (GMT -8). Example: "created" : new Date( ) List / Array A list r array is an rdered cllectin f JSON values. An array begins with [(left bracket) and ends with ] (right bracket). Values are separated by the, (cmma) character. Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 63 f 65

64 A value can be a string in duble qutes, r a number, r true r false r null, r an bject r an array. These structures can be nested. Example: "cntacts" : ["supprt@ 2.cm", "ntificatins@ 2.cm"], "recipients" : null Object A JSON Object is an unrdered set f name/value pairs. An bject begins with { (left brace) and ends with } (right brace). Each name is a string fllwed by : (cln) and then the value. The name/value pairs are separated by the, (cmma) character. Whitespace can be inserted between any pair f tkens. Because the rder is nt imprtant, members f the JSON bject can be placed anywhere within the pening and clsing braces. The fllwing tw examples are equivalent representatins f the same request cmmand: Example: {"data":{" address":"qa-fur@ 2.cm"},"header":{"cmmand":"getmember","timestamp":new Date( ),"tken":"1ea13a3d-ebc3-44ed cb5dca16a704","clientname":"apinettest","clientversin":" "}} Secure Messaging Platfrm Client Services API Admin User Guide March 2014 PAGE 64 f 65