Emails

Contents

Overview

Create Emails

List Emails

Update Emails

Delete Emails

Read An Email

Send An Email

Send A Test Email

Unschedule an email

Summary Stas for an email

Detailed Stats : Opens

Detailed Stats : Clicks

Detailed Stats : Click Details

Detailed Stats : Bounces

Detailed Stats : Unsubscribes

Emails : Targeted Lists

Overview

VR has email APIs that allow users to create, update, delete, read, launch and unschedule emails. There is also an API that provides summary stats about sent email campaigns. The attributes for emails and messages are below:

Attributes Description
name name of the email campaign
from from_address from which the email campaign will be sent
from_label the from label for the email campaign
reply_to this is the reply_to email address in the email campaign
subject subject of the email campaign
message body of the message (Please note: must include <!DOCTYPE> and <body>) For example: <!DOCTYPE><html><body>message</body></html>

postal_address

postal address of the sender. This is required by law. This attribute is broken down in to individual attributes as below
street_address
locality
region
postal code
unsubscribe_message the unsubscribe message for the email campaign. It is required by the law. The unsubscribe message should contain the {UNSUBSCRIBE_LINK}

Email: Create

The Email create API allows users to create text or html emails. from_address, from_label, subject, message, reply_to, unsubscribe_message, and postal_address are required fields to create an email.

 

A VR user can set up default from_address, from_label, reply_to, postal_address and unsubscribe_message in their account in the web application. In this case they don’t need to pass in these parameters in the request. If however these values don’t exist either in the API request or in the user’s default preferences, then the API will return an error. These fields cannot be null for compliance purposes. If null or empty values are passed in, the API will return an error and not create the email. If the message field is empty, the API returns an error. The unsubscribe_message if passed in as a request parameter must contain the string “{UNSUBSCRIBE_LINK}”.

On success, the API returns an URI of the email just created and the status of the email is set to draft.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails

Method

POST

Sample Request

Sample Response

Email:List All Emails

This API returns all the emails in the given user's VR account. Emails can be in draft,sent or scheduled state. To filter by one states, use the attribute status and the appropriate email status( draft, sent or scheduled). The type parameter can be used to limit the number of attributes returned. Type can be "basic","standard" or "all".

URL

https://vrapi.verticalresponse.com/api/v1/messages?message_type=email

Method

GET

Sample Request

Sample Response

Email: Update

The email update API updates existing emails with parameters passed in the request. The API can update the following email attributes.

   name
   from_address 
   from_label
   reply_to
   subject
   message 
   postal_address
   unsubscribe_message 


If the state of the email is delivered or pending, the email cannot be updated. message, from_address, from_label,reply_to,postal_address, unsubscribe_message cannot be null or empty string. Similar to email create, the unsubscribe_message should contain the string “{UNSUBSCRIBE_LINK}”.

Note: Emails created using the API and importing text/html within the app can be updated by the email update API. The API cannot update emails created within the VR app using templates.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/<email_id>

Method

PUT

Sample Request

Email: Delete

The email delete API will delete a given email. The delete API will not unscheduled an email that is scheduled to be sent. If the user is attempting to delete an email that is scheduled or pending, the API will throw a 400 error. The user has to unschedule the email before deleting it.

URL

 https://vrapi.verticalresponse.com/api/v1/messages/emails/email_id

Method

DELETE

Sample Request

Email: Read

The email read API returns details about a given email including status, message, the lists the email was sent to and summary stats about the email’s performance. The API takes in a type parameter, which can be one of “basic”, “standard” or “all”

Type Attributes
basic id
name
subject
status
sent_at
scheduled_at
URI
standard All basic attributes
reach
created_at
updated_at
all Standard fields
from
from_label
reply_to
postal_address
unsubcribe_text

The default mode is basic. Stats and Lists are returned for all types and are returned as URI’s.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/<email_id>

 

Method:

GET

Sample Request

Sample Response

Email Launch

The launch API is used to send or schedule an email. The API accepts the following attributes

Attributes Description
lists Array of list ids to send the email to. Maximum of 50 list ids allowed. This is a required parameter.
scheduled_at Optional date flag to specify when to send the email.

The scheduled_at parameter is optional, if it is not present, the email will be sent as soon as possible.If the scheduled_at parameter is present and is a valid date in the future, the email will be scheduled to be sent on the given date.

Errors

If any of the list ids are invalid, the API will throw an error and the email will not be sent.
If the lists array contains the “All Contacts” lists and any other list id, the API will throw an error
Lists array can however contain only the “All contacts” list id
Calling the API on an email that is in the “pending” state, will result in an error.

Note:

In general the most recent call wins. For example, scheduling an email that has been previously scheduled will update the scheduled_at field along with updating the updated_at timestamp.

Similarly, calling the API on an email that is scheduled to be sent on a future date or time, and configuring it to be sent immediately, will make the email go out as soon as possible. Also the sent_at and updated_at timestamp will be updated, scheduled_at will be reset.

 

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/<email_id>

Method

POST

Sample Request

 

Sample Response

Email: Test Launch

The API is used to send test emails.  The VR application allows users to send test emails to test their email campaign. These emails are not charged and do not count towards any email limits on the user’s plan. Test emails can be sent to a maximum of 10 users. Users can save default email addresses in VR application to use for test emails. The API has a flag “default_test_recipient_emails” which when set to true will use the email addresses saved in the app for sending test emails. In addition to the addresses already set in the app, the API also has a parameter “recipients” that accepts an array of email addresses to send test emails. All test emails will have “Test Email” in the subject.

Error 

If the user specifies "default_test_recipient_emails" and no default test recipient email addresses exist in the system, then the API will return an error. If any of the email addresses provided in the recipient’s array is invalid, the test email will not be sent and the API will return an error.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/15202/test

Method

POST

Sample Request

Sample Response

 

Email: Unschedule.

The unschedule API is used to unschedule an email that has already been scheduled to be sent on a given date in the future. The API does not take any parameter. An email that is being sent i.e in the “pending“ state cannot be unscheduled.

Error

The API will return an error if it is called on an email that has already been sent, draft or pending state

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/<email_id>/unschedule

Method

POST

Sample Request

Sample Response

Email: Summary Stats

The summary stats API provide data about the emails that were sent. The summary stats returned for emails are

Stat Description
total_contacts_sent Total number of contacts the email was sent to
reach Total number of mailable contacts the email was sent to
opens Number of times the email was opened.
open_rate % of opens for the email
clicks Number of clicks on links in the email.
click_rate % clicks for the email
unique_clicks Number of unique clicks.
bounces A bounce is when a user leaves without interacting with the email. This is the number of hard bounces for an email.
bounce_rate

Bounce rate is the % of contacts that do not interact with the email.

unsubscribes

Number of contacts that unsubscribed from the given email

unsubcribe_rate % of unscribers from the email
spam_reports Number of spam reports from the email.
spam_report_rate % of spam reports from the email.
tweets Number of times this email was shared on twitter (If the email had social sharing elements in it)
fb_likes Number of facebook likes for the email(If the email had social sharing elements in it)

URL

https://vrapi/api/v1/messages/emails/<email_id>/stats

Method

GET

Sample Request

Sample Response

Email Detailed Stats : Opens

This API returns all contacts who opened the given email. These are contacts who received the given email and opened it. The amount of contact details returned can be controlled by using the type parameter. The type parameter accepts basic,standard or all values.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/8796093022831/stats/opens

Method

GET

Sample Request

Sample Response

Email Detailed Stats : Clicks

This API returns all links in a given email and the number of times those links were clicked.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/8796093022831/stats/clicks

Method

GET

Sample Request

Sample Response

Email Detailed Stats : Click Details

This API returns all contacts who clicked on a particular link in the given email. These are contacts who received the given email, opened it and clicked on a particular link present in the email. The number of contact details returned can be controlled by using the type parameter. The type parameter accepts basic,standard or all values. In addition to the email addresses, first name and last name of the contact who clicked on the link, the API also returns timestamp of the click and the total number of times the contact clicked on the given link.. The click_id in the API endpoint can be obtained by the "clicks" API. Refer the response for the Email Detailed Stats: Clicks API.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/8796093022831/stats/clicks/

Method

GET

Sample Request

Sample Response

Email Detailed Stats : Unsubscribes

This API returns all contacts who unsubscribed from a given email. If there are no contacts that unsubscribed from a given email, then the API returns an empty array. The contact's attributes returned can be controlled using the type parameter. The type parameter accepts "basic", "standard" or "all" values.

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/8796093022831/stats/unsubcribes

Method

GET

Sample Request

Sample Response

Email Detailed Stats : Bounces

This API returns all contacts who bounced from a given email. If there are no contacts that bounced from a given email, then the API returns an empty array. The contact's attributes returned can be controlled using the type parameter. The type parameter accepts "basic", "standard" or "all" values. This API will only return contacts who have hard bounced from an email. Soft bounces will not be returned.

Note:

Hard Bounce: A permanent delivery issue like a non-existent email address

Soft Bounce: A temporary delivery issue like a full mailbox or technical issue

URL

https://vrapi.verticalresponse.com/api/v1/messages/emails/8796093022831/stats/bounces

Method

GET

Sample Request

Sample Response

Email: Targeted Lists

The API returns all the lists to which the given email has been sent, scheduled to be sent or in the draft mode. Attributes of lists returned depend on the type parameter passed in. For more on type parameter in lists, check the lists overview section

URL

 

 

https://vrapi/api/v1/messages/emails/<email_id>/lists

Method

GET

Sample Request

Sample Response