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": "[email protected]"
            },
            "recipient": {
                "name": "Recipient Name",
                "initials": "Recipient N.",
                "email": "[email protected]",
                "photo_url": "http://privasfer.com/images/no_image.png",
                "timezone": "Europe/Vilnius"
            },
            "recipient_email": "[email protected]",
            "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": "[email protected]"
            },
            "recipient": {
                "name": "Recipient Name",
                "initials": "Recipient N.",
                "email": "[email protected]",
                "photo_url": "http://privasfer.com/images/no_image.png",
                "timezone": "Europe/Vilnius"
            },
            "recipient_email": "[email protected]",
            "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":"[email protected]", "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": "[email protected]"
            },
            "recipient": {
                "name": "Recipient Name",
                "initials": "Recipient N.",
                "email": "[email protected]",
                "photo_url": "http://privasfer.com/images/no_image.png",
                "timezone": "Europe/Vilnius"
            },
            "recipient_email": "[email protected]",
            "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.