Emails
Contents
Detailed Stats : Click Details
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} |
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
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
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
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
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
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
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
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
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
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
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
https://vrapi/api/v1/messages/emails/<email_id>/lists
Method
GET
Sample Request
Sample Response
