Messages

Contents

Overview

List All Messages

Search Messages

Overview

VerticalResponse helps businesses easily create professional and functional email campaigns. VR also allows users to reach and increase their social audience via social posts. Messages in VR encompass both emails and social posts. The API follows the same vernacular as well. APIs for Create, Read, Update, and Delete work on emails and social posts individually. List and Find work at the messages level.

Messages attributes are shared between emails and social posts. Apart from these emails and social posts also have some specific attributes. Check the Emails and Social Posts section for more information. 

Attribute Name
Description
id message id
name Name of the message.
subject Subject of the message
message_type Type of message. Type can be email or social post
status Status of the message. A message can be in draft/sent/scheduled state.
sent_at Timestamp when the message was sent to intended recipients
scheduled_at

Timestamp when the message is scheduled to be sent to intended recipients

created_at

Timestamp when the message was created.

updated_at

Timestamp when the message was updated. Same as created, if never updated.

URI

URI of the message.

Reach:

Reach parameter is returned for every message. Reach for emails is the number of  mailable contacts the email was sent to. Reach for social posts is the reach of the particular social network in which the post was shared. If a post was shared in multiple social then reach is the sum of the reach of the individual networks.

For example:  

Reach for Email  = Number of mailable contacts of the lists the email was sent to (de-duped)

Reach for Social Post = Reach of social network (500 FB friends) + 100 Twitter followers if the post was shared on both Facebook and twitter.

Messages: List

The API lists all the messages in a user’s account. This includes both emails and social posts that are in draft, scheduled, or sent states. The list is ordered by most recently sent. The API accepts a type parameter and depending on “basic” or “standard”, appropriate message attributes will be returned.

 

Note: there is no "all" parameter. If the "all" parameter is passed in, type will return the "standard" result set. The default type is basic.

 

Date Values and Meaning

 

sent_at
Description State
null null Draft
valid date null delivered
null valid date scheduled to be sent
valid date valid date Originally scheduled email now Delivered. sent_at = scheduled_at

URL

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

Method

GET

Sample Request

Sample Response

Messages: Find

This API is used to find messages based on search parameters. The parameters by which the messages can be searched are  

Parameter
Description
message_type Messages can be emails or social posts. Accepted values are ‘email’ or ‘social post’
status Status of the message. This can be either ‘draft’, ‘scheduled’, ‘delivered’
created_since Timestamp when the message was created. The accepted format is yyyy-mm-dd
created_until created_since and created_until are used to specify a date range to search messages by the date on which they were created.
scheduled_since Timestamp when message was scheduled to be delivered to its intended recipients. Accepted format is yyyy-mm-dd
scheduled_until scheduled_since and scheduled_until are used to specify a date rage to search messages by their scheduled delivery date
sent_since Timestamp when message was sent to its intended recipients. Accepted format is yyyy-mm-dd
sent_until

sent_since and sent_until are used to specify a date range to search messages by their sent date

On success, messages that match the search query are returned as an array. If no messages match the given search, an empty array is returned. Note: The API will consider more than one query parameter as an AND query. It is important to remember what the different dates and the message status mean. For e.g. A message in scheduled state can only have a valid scheduled_at date. Providing both sent and scheduled date ranges along with a status value of “scheduled” will yield no results. For more on message states and dates, check the messages overview section.

URL

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

Method

GET

Sample Request