The StayPrivate API

The StayPrivate API enables developers to use REST methods to add secure email sending capability to a business application. In order to support the sending of emails with one or more attachments, the API incorporates various methods for preparing, uploading and deleting attachments.

Please note that to make use of this API you need to have already registered the organization domain with StayPrivate.

Authorization

Each API request header needs to specify:

the content type;

the unique company API ID; and

a valid JSON web token (JWT) authenticated by your application server.

Typical Request Headers


              
                Content-Type: application/json

                SP-Company-Api-Id: <insert your Unique Company API ID>

                Authorization: Bearer <insert the JWT token>

You can find your unique company API ID by logging into the StayPrivate dashboard at https://admin.stayprivate.com.

Before you can use the API, you need to generate a private/public key pair and register the public key in the StayPrivate dashboard. The below shows an example of how to generate an RSA2048 key pair using OpenSSL. Please note that it is your responsibility to generate your public/private key pair and to keep your private key secure.

Key generation example


              
                openssl genrsa -out privatejwt.key 2048 - to generate a private key without a passphrase

                openssl genrsa -des3 -out privatejwt.key 2048 - generate a private key with a passphrase

                openssl rsa -in privatejwt.key -pubout -out publicjwt.key - to generate a public key from the private key

The JWT token must include the company API id as issuer (iss) and a valid expiry time (exp) and be signed using the corresponding private key for the public key registered in the StayPrivate dashboard.

Required JWT Fields


                iss: <insert your Unique Company API ID>

                exp: <expiry time>

                alg: <RS256 or similar>

Using the API

For emails without any attachments it is possible to send a secure email using just a single API call. For emails with attachments you should follow the following three-step process:

Prepare the email - this generates a unique email reference for the email
Upload an attachment to the email - repeat if required
Send the email

Methods

Prepare Email

POST https://api.stayprivate.com/1.0/emails/prepare
POST https://api.stayprivate.com/1.0/emails/<emailRef>/prepare

This method is used to prepare an email and is always required if the email has attachments, but can also be used for saving a draft of an email. To prepare a new email, use the first version of the URL, without <emailRef>. To save a new draft of a previously prepared email, use the second version of the URL and include the relevant email reference in <emailRef>.

Request body: the following required and optional parameters should be specified in JSON format:

senderEmail (required) - the sender email (which must belong to a domain associated with the company)

emailSubject (optional) - the subject of the email

emailBody (optional) - the body of the email.

Request header: the following parameters are required:

Content-Type: application/json

SP-Company-Api-Id - the Unique Company API ID

Authorization - the JWT token

A response is returned in JSON format. If successful, the HTTP status code 200 is returned, together with the response body below. The email reference in the response should be used for saving further drafts of the email, uploading email attachments and for sending the email.

{"success": true, "data": {"emailRef": <email reference>}}

If the method fails, an HTTP status code of 401, 422 or 500 is returned, together with the following response body:

{"success": false, "error": {"code": <the error code>, "message": <the error message>}}

For an example of how to prepare an email, the following cURL command line format could be used to prepare a new email with an email subject and body:


              
                curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -H "SP-Company-Api-Id: <company api id>" -d '{"senderEmail":"<sender email>", "emailSubject":"<email subject>", "emailBody":"<email body>"}' https://api.stayprivate.com/1.0/emails/prepare

Upload Attachment

POST https://api.stayprivate.com/1.0/emails/<emailRef>/attachments/upload
POST https://api.stayprivate.com/1.0/emails/<emailRef>/attachments/<fileRef>/upload

This method is used to upload an attachment to an email. The email must have already been prepared before an attachment can be uploaded, and the email reference should be used as <emailRef>. To upload a new attachment, use the first version of the URL, without <fileRef>. To update an attachment which has already been uploaded use the second version of the URL and use the relevant file reference <fileRef>.

Request body: the email attachment should be uploaded as an input file with id/name "emailAttachment". The following optional parameter can also be specified:

reqESignFlag (optional) - include and set to Y if the attachment requires e-signing. Set to N or omit if this is not the case.

Request header: the following parameters are required:

Content-Type: multipart/form-data

SP-Company-Api-Id - the Unique Company API ID

Authorization - the JWT token

A response is returned in JSON format. If successful, the HTTP status code 200 is returned, together with the response body below. The file reference in the response is used for updating the attachment, if required.

{"success": true, "data": {"fileRef": <file reference>; "emailRef": <email reference>}}

If the method fails, an HTTP status code of 401, 422 or 500 is returned, together with the following response body:

{"success": false, "error": {"code": <the error code>, "message": <the error message>}}

For an example of how to upload an attachment, the following cURL command line format could be used to upload a file which requires e-signing:


              
                curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: multipart/form-data" -H "SP-Company-Api-Id: <company api id>" -F "reqESignFlag=Y" -F "emailAttachment=@<file path>" https://api.stayprivate.com/1.0/emails/{emailRef}/attachments/upload

Delete Attachment

DELETE https://api.stayprivate.com/1.0/emails/<emailRef>/attachments/<fileRef>

This method is used to remove and delete an attachment to an email. An attachment can only be deleted if the the email has not yet been sent.

Request body: none.

Request header: the following parameters are required:

SP-Company-Api-Id - the Unique Company API ID

Authorization - the JWT token

A response is returned in JSON format. If successful, the HTTP status code 200 is returned, together with the response body below.

{"success": true, "data": {"emailRef": <email reference>}}

If the method fails, an HTTP status code of 401, 422 or 500 is returned, together with the following response body:

{"success": false, "error": {"code": <the error code>, "message": <the error message>}}

For an example of how to upload an attachment, the following cURL command line format could be used to upload a file from the server that requires e-signing:


              
                curl -X DELETE -H "Authorization: Bearer <bearer_token>" -H "SP-Company-Api-Id: <company api id>" https://api.stayprivate.com/1.0/emails/<emailRef>/attachments/<fileRef>

Send Email

POST https://api.stayprivate.com/1.0/emails/send
POST https://api.stayprivate.com/1.0/emails/<emailRef>/send

This method is used to send an email. To send an email which has not been prepared, use the first version of the URL, without <emailRef>. To send a previously prepared email, use the second version of the URL and include the relevant email reference in <emailRef>. The email address of the sender (senderEmail) is required for a new email but should not be specified for an email which has already been prepared.

Request body: the following required and optional parameters should be specified in JSON format:

senderEmail (optional) - the sender email (which must belong to a domain associated with the company) and is only required for a new email

emailSubject (optional) - the subject of the email

emailBody (optional) - the body of the email

emailToList (optional) - a semi-colon separated of email "To" recipients

emailCcList (optional) - a semi-colon separated of email "Cc" recipients

emailBccList (optional) - a semi-colon separated of email "Bcc" recipients

Request header: the following parameters are required:

Content-Type: application/json

SP-Company-Api-Id - the Unique Company API ID

Authorization - the JWT token

{"success": true, "data": {"status": "S"}}

If the method fails, an HTTP status code of 401, 422 or 500 is returned, together with the following response body:

{"success": false, "error": {"code": <the error code>, "message": <the error message>}}

For an example of how to prepare an email, how to send an email, the following cURL command line format could be used to send a prepared email to "To" and "Bcc" recipients (noting that senderEmail is not required for a prepared email):


              
                curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -H "SP-Company-Api-Id: <company api id>" -d '"emailSubject":"<email subject>", "emailBody":"<email body>", "emailToList":"<email to list>", "emailBccList":"<email bcc list>"}' https://api.stayprivate.com/1.0/emails/<emailRef>/send