Spec - Broadcasts

Get Broadcasts
Get Broadcast Stats
Get Broadcast Body
Queue Mail
Send Test Mail
Reset Contact Drip Campaign

Get Broadcasts

This function allows the caller to get all of the broadcasts for a group.

Input

Group ID and Contact ID. If omitted, return all broadcasts for the account.

To get broadcasts sent after a sent date/time obtained earlier, pass Datetime_sent = “(senttimevalue)”. To get broadcasts modified after a modified date/time obtained earlier, pass update_timestamp=”(updatedtimevalue)”.

Specify account_id for shared access to broadcasts in another account. Specify get_all=”true” to return all broadcasts that the user has access to, including shared access.

Specify message_type to filter the types of broadcasts. Values accepted are ‘drip’ to filter drip campaigns broadcasts; ‘journeys’ to filter broadcasts sent from journeys; default to ‘Broadcasts’ message type if not specified.

Output

Broadcast ID, Status (Queued or Sent), Subject, Account Number, GroupID, GroupName, NumberOfRecipients, DatetimeQueued, DatetimeScheduledForDelivery, DateTimeSent, RecipientFiltersUsed, NumberOfClicks, NumberOfReads, UpdatedTimestamp for each broadcast, JourneyID and JourneyName if broadcast belongs to a journey.

Example Request 1

<GetBroadcastsRequest Group_id="9224"></GetBroadcastsRequest>

Example Request 2

<GetBroadcastsRequest Datetime_sent="2012-03-01 12:00:00"></GetBroadcastsRequest>

Example Request 3

<GetBroadcastsRequest updated_timestamp="2012-12-03 13:54:23"></GetBroadcastsRequest>

Example Request 4 (shared access)

<GetBroadcastsRequest account_id="1392"></GetBroadcastsRequest>

Example Request 5 (shared access with get_all)

<GetBroadcastsRequest get_all="true"></GetBroadcastsRequest>

Example Request 6 (filter by contact_id)

<GetBroadcastsRequest Group_id="9224" Contact_id="123"></GetBroadcastsRequest>

Example Request 7 (to get Drip Campaigns only)

<GetBroadcastsRequest Group_id="9224" message_type="drip"></GetBroadcastsRequest>

Example Request 8 (to get Journeys only)

<GetBroadcastsRequest Group_id="9224" message_type="journeys"></GetBroadcastsRequest>

Example Response

<GetBroadcastsResponse>
    <Result>Success</Result>
    <Broadcasts>
        <Broadcast>
            <Broadcast_id>389</Broadcast_id>
            <Status>Sent</Status>
            <Subject>Sample Subject</Subject>
            <AccountNumber>23</AccountNumber>
            <GroupID>54</GroupID>
            <GroupName>My Group 1</GroupName>
            <NumberOfRecipients>230</NumberOfRecipients>
            <DatetimeQueued>2010-08-31 14:23:56</DatetimeQueued>
            <DatetimeScheduledForDelivery>2010-09-03 12:00:00</DatetimeScheduledForDelivery>
            <DatetimeSent>2010-09-03 12:05:00</DatetimeSent>
            <RecipientFiltersUsed>All Contacts</RecipientFiltersUsed>
            <NumberOfClicks>329</NumberOfClicks>
            <NumberOfReads>892</NumberOfReads>
            <UpdatedTimestamp>2012-11-24 12:34:56</UpdatedTimestamp>
        </Broadcast>
        <Broadcast>
            <Broadcast_id>393</Broadcast_id>
            <Status>Queued</Status>
            <Subject>AnotherSubject</Subject>
            <AccountNumber>23</AccountNumber>
            <GroupID>55</GroupID>
            <GroupName>My Group 2</GroupName>
            <JourneyID>5</JourneyID>
            <JourneyName>Test Journey</JourneyName>
            <NumberOfRecipients>786</NumberOfRecipients>
            <DatetimeQueued>2012-11-21 01:23:45</DatetimeQueued>
            <DatetimeScheduledForDelivery>2013-01-02 13:30:00</DatetimeScheduledForDelivery>
            <DatetimeSent></DatetimeSent>
            <RecipientFiltersUsed>All Active Contacts in Group</RecipientFiltersUsed>
            <NumberOfClicks>493</NumberOfClicks>
            <NumberOfReads>1027</NumberOfReads>
            <UpdatedTimestamp>2012-11-23 10:43:21</UpdatedTimestamp>
        </Broadcast>
    </Broadcasts>
</GetBroadcastsResponse>

Get Broadcast Stats

This function allows the caller to get stats for a broadcast

Input

Broadcast ID (required).

Specify order_by (optional) for the sort sequence of the contacts returned. Order by can be Name, Company, LastRead, or ClicksPlusReads (default). Name and company are in ascending alphanumeric order with blanks last. LastRead and ClicksPlusReads are in descending numeric order.

Pass limit=n to return the first n matching contacts.

Pass message_type=’drip’ along with the drip campaign broadcast_id to get drip campaign stats.

Pass message_type=’personal_email’ along with the broadcast_id to get email stats.

Pass start_chunk_size=n to change the default pagination chunk size to n (default 10000).

Pass start_chunk_page=n to get the nth page of results (numbering starts at 0).

Output

For each contact in the broadcasts - contact ID, send data, read data, click data, bounce data.

Journey ID and journey name if the broadcast belongs to a journey.

Example Request 1

<GetBroadcastStatsRequest broadcast_id="994" order_by="Company" limit="100"></GetBroadcastStatsRequest>

Example Request 2 (to get Drip Campaign stats)

<GetBroadcastStatsRequest broadcast_id="995" message_type="drip"></GetBroadcastStatsRequest>

Example Request 3 (to get Personal Email stats)

<GetBroadcastStatsRequest broadcast_id="996" message_type="personal_email"></GetBroadcastStatsRequest>

Example Request 4 (get the second page of 1000 contacts)

<GetBroadcastStatsRequest broadcast_id="994" start_chunk_size=1000 start_chunk_page=1></GetBroadcastStatsRequest>

Example Response

<GetBroadcastStatsResponse>
    <Result>Success</Result>
    <Broadcast_id>343567</Broadcast_id>
    <AccountNumber>78</AccountNumber>
    <JourneyID>4</JourneyID>
    <JourneyName>Test Journey</JourneyName>
    <Contacts>
        <Contact>
            <Contact_id>994</Contact_id>
            <Contact_firstname>John</Contact_firstname>
            <Contact_lastname>Smith</Contact_lastname>
            <Contact_email>john.smith@gmail.com</Contact_email>
            <Company>JS Co</Company> 
            <Send_data>
                <DatetimeSent>2010-09-03 12:00:00</DatetimeSent>
            </Send_data>
            <Read_data>
                <DatetimeRead>2010-09-05 13:45;45</DatetimeRead>
                <DatetimeRead>2010-09-07 08:00:00</DatetimeRead>
            </Read_data>
            <Click_data>
                <Click>
                    <LinkClicked>http://www.mysite.com/mylink1.html</LinkClicked>
                    <DatetimeClicked>2010-09-05 13:47:08</DatetimeClicked>
                </Click>
                <Click>
                    <LinkClicked>http://www.mysite.com/mylink2.html</LinkClicked>
                    <DatetimeClicked>2010-09-05 13:48:18</DatetimeClicked>
                </Click>
            </Click_data>
            <Bounce_data></Bounce_data>
        </Contact>
        <Contact>
            <Contact_id>995</Contact_id>
            <Contact_firstname>Jane</Contact_firstname>
            <Contact_lastname>Doe</Contact_lastname>
            <Contact_email>jane.doe@gmail.com</Contact_email>
            <Send_data>
                <DatetimeSent>2010-09-03 12:00:01</DatetimeSent>
            </send_data>
            <read_data>
                    <datetimeread>2010-09-05 15:25:15</datetimeread>
                    <datetimeread>2010-09-05 18:01:30</datetimeread>
            </read_data>
            <click_data>
                <click>
                    <linkclicked>http://www.mysite.com/mylink2.html</linkclicked>
                    <datetimeclicked>2010-09-05 16:47:08</datetimeclicked>
                </click>
                <click>
                    <linkclicked>http://www.mysite.com/mylink4.html</linkclicked>
                    <datetimeclicked>2010-09-05 19:18:28</datetimeclicked>
                </click>
            </click_data>
            <bounce_data></Bounce_data>
        </Contact>
        <Contact>
            <Contact_id>996</Contact_id>
            <Contact_firstname>Johnny</Contact_firstname>
            <Contact_lastname>English</Contact_lastname>
            <Contact_email>johnny.english@gmail.com</Contact_email>
            <Company>JE Co</Company> 
            <Send_data>
                <DatetimeSent>2010-09-03 12:00:01</DatetimeSent>
            </Send_data>
            <Read_data></Read_data>
            <Click_data></Click_data>
            <Bounce_data>
                <Bounce>
                    <BounceCode>B</BounceCode>
                    <BounceReasonShort>routing-errors</BounceReasonShort>
                    <BounceReasonLong>4.4.4 (unable to route: dns lookup failure) </BounceReasonLong>
                </Bounce>
            </Bounce_data>
        </Contact>
    </Contacts>
</GetBroadcastStatsResponse>

Get Broadcast Body

This function allows the caller to get HTML message and text message of a broadcast

Input

broadcast_id (required)
account_id (required for shared access users)
group_id (required for shared access users)
include_rfc822 (true to return broadcast message in RFC822 format)
contact_id (required when passing include_rfc822)

Output

AccountNum
GroupID
GroupName
BroadcastID
FromName
FromEmail
Contact_id (if contact_id passed)
Contact_firstname (if contact_id passed)
Contact_lastname (if contact_id passed)
Contact_email (if contact_id passed)
Subject
Action
DatetimeQueued
DatetimeSent
MessageHTML
MessageText
RFC822 (if include_rfc822 passed)

Example Request

<GetBroadcastBodyRequest broadcast_id="646064"/>

Example Request (include RFC822)

<GetBroadcastBodyRequest broadcast_id="646064" contact_id="7" include_rfc822="true"/>

Example Request (Shared Access)

<GetBroadcastBodyRequest broadcast_id="646064" account_id="1" group_id="1"/>

Example Response

<GetBroadcastBodyResponse>
    <Result>Success</Result>
    <AccountNum>38193</AccountNum>
    <GroupID>1</GroupID>
    <GroupName>My Group</GroupName>
    <BroadcastID>646064</BroadcastID>
    <FromName>support</FromName>
    <FromEmail>support@company.org</FromEmail>
    <Contact_id>123</Contact_id>
    <Contact_firstname>John</Contact_firstname>
    <Contact_lastname>Smith</Contact_lastname>
    <Contact_email>john.smith@gmail.com</Contact_email>
    <Subject>Happy Birthday</Subject>
    <Action>Sent Email</Action>
    <DatetimeQueued>2014-06-25 21:06:00</DatetimeQueued>
    <DatetimeSent>2014-06-30 21:05:00</DatetimeSent>
    <MessageHTML>&lt;html&gt;
    &lt;head&gt;
            &lt;title&gt;Message for you&lt;/title&gt;
    &lt;/head&gt;
    &lt;body style="cursor: auto;"&gt;
    &lt;table id="Background" width="100%"&gt;
            &lt;tbody&gt;
                    &lt;tr&gt;
                            &lt;td&gt;
                            &lt;p&gt;Write your email message here.&lt;/p&gt;

                            &lt;p&gt;You can also import any saved email or one of our professional templates using the "Template" button above.&lt;/p&gt;
                            &lt;/td&gt;
                    &lt;/tr&gt;
            &lt;/tbody&gt;
    &lt;/table&gt;
    &lt;/body&gt;
    &lt;/html&gt;</MessageHTML>
    <MessageText>Message for you

        Write your email message here.

        You can also import any saved email or one of our professional
        templates using the "Template" button above.</MessageText>
    <RFC822>
    From: test@test.org
    To: receiver@gmail.com
    Subject: Queue

        Message for you

        Write your email message here.

        You can also import any saved email or one of our professional
        templates using the "Template" button above.
    </RFC822>
</GetBroadcastBodyResponse>

Queue Mail

This function allows the caller to queue mail to a group.

Input

Group ID or Group Name in request tag, From Name, From Email, Subject, Message HTML or Media ID, DeliveryDateTime

Output

Success or Failure

Example Request 1

<QueueMailRequest group_name="MyTeam">
    <From_name>My Organization</From_name>
    <From_email>myorganization@my.org</From_email>
    <Subject>A Cool Test Email</Subject>
    <Message><![CDATA<html><head>(etc. continue HTML)</body></html>]]></Message>
    <Delivery_date_time>2010-05-01T11:00:00</Delivery_date_time>
</QueueMailRequest>

Example Request 2

<QueueMailRequest Group_id="8903">
    <From_name>My Organization</From_name>
    <From_email><myorganization@my.org</From_email>
    <Subject>A Cool Test Email</Subject>
    <Message MediaID="5"></Message>
    <Delivery_date_time>2010-05-01T11:00:00</Delivery_date_time>
</QueueMailRequest>

Example Response

<QueueMailResponse>
    <Result>Success</Result>
</QueueMailResponse>

Send Test Mail

This function allows the caller to send a test email to up to five addresses.

Input

From Name, From Email, Group ID or Group Name (test recipients will be added to this group if they are not already members), Subject, Message HTML or Media ID, up to 5 recipients.

Output

Success or Failure

Example Request

<SendTestMailRequest Group_id="9">
    <From_name>My Organization</From_name>
    <From_email>myorganization@my.org</From_email>
    <Subject>A Cool Test Email</Subject>
    <Message><![CDATA<html><head>(etc. continue HTML)</body></html>]]></Message>
    <Recipients>
         <Recipient>testmail1@testdomain.com</Recipient>
         <Recipient>testmail2@testdomain.com</Recipient>
    </Recipients>
</SendTestMailRequest>

Example Response

<SendTestMailResponse>
    <Result>Success</Result>
</SendTestMailResponse>

Reset Contact Drip Campaign

This function allows the caller to reset the drip campaign for the specified contact. Search criteria can be group_id, contact_id, firstname, lastname, email. Each group and each contact search criteria must return a single unique. drip_campaign_id is also required.

Input

Group ID or Group name for Group search criteria, must return a single unique group. Contact IDs of Contacts to reset, or search criteria for Contacts to reset. Search criteria can be contact_id, firstname, lastname, email. Each contact’s search criteria must return a single unique contact. Drip campaign ID is also required. Account ID for shared access.

Output

Success or failure.

Example Request 1

<ResetContactDripCampaignRequest group_id='4' drip_campaign_id='1' contact_id='123'></ResetContactDripCampaignRequest>

Example Request 2

<ResetContactDripCampaignRequest group_id='4' drip_campaign_id='1' contact_id='123' account_id='38193'></ResetContactDripCampaignRequest>

Example Response

<ResetContactDripCampaignResponse>
    <Result>Success</Result>
</ResetContactDripCampaignResponse>

Topics

Spec - Broadcasts

Table Of Contents

Get Broadcasts

Input

Output

Example Request 1

Example Request 2

Example Request 3

Example Request 4 (shared access)

Example Request 5 (shared access with get_all)

Example Request 6 (filter by contact_id)

Example Request 7 (to get Drip Campaigns only)

Example Request 8 (to get Journeys only)

Example Response

Get Broadcast Stats

Input

Output

Example Request 1

Example Request 2 (to get Drip Campaign stats)

Example Request 3 (to get Personal Email stats)

Example Request 4 (get the second page of 1000 contacts)

Example Response

Get Broadcast Body

Input

Output

Example Request

Example Request (include RFC822)

Example Request (Shared Access)

Example Response

Queue Mail

Input

Output

Example Request 1

Example Request 2

Example Response

Send Test Mail

Input

Output

Example Request

Example Response

Reset Contact Drip Campaign

Input

Output

Example Request 1

Example Request 2

Example Response