Mails

We'll assume you've already got the API authentication settled and you have our API token with you.

In this area we will tell you how to list or even send mails with secured files.

 

List sent mails in your account #

By making GET request to the /api/mails endpoint, you can list all sent mails in your account.

curl https://privasfer.com/api/mails \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

As a result, you get the details for every file you've uploaded.

{
    "data": [
        {
            "id": "aaeba4fb-ac69-448b-94b3-f48162ea6c89",
            "identifier": "awGj",
            "subject": "Secure files",
            "body": "<p>Hi, <br /> sending you files.</p>",
            "sender": {
                "name": "Sender name",
                "email": "sender@email.address"
            },
            "recipient": {
                "name": "Recipient Name",
                "initials": "Recipient N.",
                "email": "recipient@email.address",
                "photo_url": "http://privasfer.com/images/no_image.png",
                "timezone": "Europe/Vilnius"
            },
            "recipient_email": "recipient@email.address",
            "created_at": "2019-05-08 16:21:47",
            "sent_at": "2019-05-08 16:21:48",
            "status": "success",
            "opened_at": ""
        }

        // ...
    ]
}

Read more about returned properties here.

Extra parameters #

name value description
include download, download.files, author Include mail related data. Example: /api/mails?include=download,download.files
sort subject, recipient_email, created_at, sent_at Include category object. Example: /api/mails?sort=subject to make reverse sorting use negative value /api/mails?sort=-subject
keyword search keyword Perform search in identifier, subject, recipient_email, recipient.name, created_by_name field by given value. Example: /api/mails?keyword=test

 

Get a specific sent mail via the API #

If you want to get specific sent mail, you can specify file ID in endpoint. The example below will show the details of sent mail ID aaeba4fb-ac69-448b-94b3-f48162ea6c89.

curl https://privasfer.com/api/mails/aaeba4fb-ac69-448b-94b3-f48162ea6c89 \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Single sent mail payload.

{
    "data": {
            "id": "aaeba4fb-ac69-448b-94b3-f48162ea6c89",
            "identifier": "awGj",
            "subject": "Secure files",
            "body": "<p>Hi, <br /> sending you files.</p>",
            "sender": {
                "name": "Sender name",
                "email": "sender@email.address"
            },
            "recipient": {
                "name": "Recipient Name",
                "initials": "Recipient N.",
                "email": "recipient@email.address",
                "photo_url": "http://privasfer.com/images/no_image.png",
                "timezone": "Europe/Vilnius"
            },
            "recipient_email": "recipient@email.address",
            "created_at": "2019-05-08 16:21:47",
            "sent_at": "2019-05-08 16:21:48",
            "status": "success",
            "opened_at": ""
        }
}

Return properties #

  • id: an internal identifier.
  • identifier: unique email identifier visible in email, sms and download page.
  • subject: email subject visible in email and download page.
  • body: the email body is visible in email and download pages. As you can see, body could be plain text of html. Max 10000 symbols is allowed for this field - including html tags.
  • sender: user name and email, that created and send this email.
  • recipient: object with recipient data. Object included only if recipient has account in privasfer.com system.
  • recipient_email: recipient email address.
  • recipient_phone_number: recipient phone number. This property available only if recipient phone number is passed when creating an email.
  • created_at: date and time when mail was created. Time is formatted to your time zone(time zone can be changed in your profile settings).
  • sent_at: date and time when mail was sent. Time is formatted to your time zone(time zone can be changed in your profile settings). We are using third party service to guarantee that all your emails will reach recipient, but we can not guarantee that these services up time is 100%. So we are sending emails in background, and repeating this process until mail is sent successfully and sent_at date time represent when email was successfully sent to recipient.
  • status: represent mail send status. First of all status is pending, then status is changed to success or failed.
  • opened_at: date and time, when last time email was opened.

 

Sending email via the API #

To send email, make a POST request to the /api/mails endpoint. Here's an example.

curl -X POST https://privasfer.com/api/mails \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"files":["811f216d-eb8f-46fc-a263-08387c70a4a4"], "recipient_email":"recipient@email.ltd", "recipient_phone_number":"+37000000000", "subject":"Your email subject", "body":"<p>Your email body</p>"}'

Form fields #

name description type
files List of files ID’s you have uploaded. More about files uploading you can read here. array
recipient_email Recipient email address. string
recipient_phone_number (optional) Recipient phone number. Phone number should be given with valid country code. If you pass phone number, the PIN code will be sent to the customer via SMS, otherwise PIN code will be sent to the original email address. string
subject (optional) Email subject. Maximum 255 symbols. Default subject is Secure files string
body (optional)

Email body. Body can be plain text or formatted html. Max 10000 symbols, including html tags.

Allowed HTML tags: b,strong,i,em,u,ul,ol,li,p,br,h1,h2,h3

string

If the API call succeeded, you'll be given output like this.

{
    "data": {
            "id": "ba44b83f-ee58-4361-8e56-ec3e738aa0c2",
            "identifier": "VUwD",
            "subject": "Your email subject",
            "body": "<p>Your email body</p>",
            "sender": {
                "name": "Sender name",
                "email": "sender@email.address"
            },
            "recipient": {
                "name": "Recipient Name",
                "initials": "Recipient N.",
                "email": "recipient@email.address",
                "photo_url": "http://privasfer.com/images/no_image.png",
                "timezone": "Europe/Vilnius"
            },
            "recipient_email": "recipient@email.address",
            "recipient_phone_number": "+37000000000",
            "created_at": "2019-05-17 10:13:37",
            "status": "pending",
            "opened_at": ""
        }
}

 

Error handling #

If an error occurred, you'll be given a non-HTTP/200 response code. The resulting payload might look like this.

{
    "message": "The given data was invalid.",
    "errors": {
        "files": [
            "The files field is required."
        ]
    }
}

 

Deleting a sent email #

Use the DELETE request to delete a sent mail through the API. In this example, we'll delete a sent mail with ID ba44b83f-ee58-4361-8e56-ec3e738aa0c2.

curl -X DELETE https://privasfer.com/api/mails/ba44b83f-ee58-4361-8e56-ec3e738aa0c2 \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

After successful delete request you will receive a 204 HTTP status.