Overview

This service provides a way to simply and easily consume account activity data in real-time as events (clicks, opens, bounces, etc.) occur. This can be extremely useful for applications using MessageGears that need to capture their activity data more frequently than once a day (i.e. for a job dashboard). The data is formatted using exactly the same XML structure as the AccountActivity API results. The only difference is that the data will come from a queue in many small XML payloads.

 

Process

Implementation

Amazon provides their Simple Queue Service as a way to easily and securely transfer data using their API.

 

Response Values

Common response values for the v3.1 event feed:

Element Name	Description
ActivityItems	The root element of the XML response.
RequestId	The MessageGears request id of the job of which the activity items belongs.
ActivityId	The unique activity id for an individual activity item.
Timestamp	The time that the event/activity item occurred.
EmailAddress	The email address of the recipient responsible for the activity item.
IpAddress	The ip address that generated the activity.
CorrelationId (Optional)	The correlation id provided with the invocation of this job, if supplied. This field allows you to supply your own job id. This ID is designed to make it easier to match events coming out of MessageGears with the job they belong to in your own system.
RecipientId (Optional)	The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.
JobCategory (Optional)	The category for that job invocation, if supplied. The job category creates the opportunity for unique and aggregate job reporting using detailed event information.

 

Email Examples

Click Activity Response

<ActivityItems>
 <ClickActivity>
  <RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-14T15:50:19.491-04:00</Timestamp>
  <IpAddress>74.60.196.56</IpAddress>
  <UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>
  <Url>http://www.mycompany.com</Url>
  <UrlName>Home Page</UrlName>
  <Microsite>true</Microsite>
 </ClickActivity>
</ActivityItems>

 

Element Name	Description
ClickActivity	The element containing all the click information. This is a repeating element, one for each click event for the specified day.
UserAgent	The browser type (or email client) used to provide the event.
Url	The URL of the clicked link.
UrlName	The name (if any) of the link you provided in the template when the link was made trackable.
Microsite	Will be set to "true" if this event originated from a microsite version of an email message.

 

Open Activity Response

<ActivityItems>
 <OpenActivity>
  <RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-14T15:49:16.064-04:00</Timestamp>
  <IpAddress>74.60.196.56</IpAddress>
  <UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>
  <Microsite>true</Microsite>
 </OpenActivity>
</ActivityItems>

 

Element Name	Description
OpenActivity	The element containing all the open information. This is a repeating element, one for each open event for the specified day.
UserAgent	The browser type (or email client) used to provide the event.
Microsite	Will be set to “true” if this event originated from a microsite version of an email message.

 

Delivery Activity Response

<ActivityItems>
 <DeliveredMessageActivity>
  <RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>
  <IpAddress>74.125.47.27</IpAddress>
 </DeliveredMessageActivity>
</ActivityItems>

 

Element Name	Description
DeliveredMessageActivity	The element containing all the delivery information. This is a repeating element, one for each email delivered for the specified day.

 

Bounce Activity Response

<ActivityItems>
 <BouncedMessageActivity>
  <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>
  <Category>Invalid Recipient</Category>
  <CategoryCode>10</CategoryCode>
  <Details>550-5.1.1 The email account that you tried to reach does not exist.</Details>
  <IpAddress>74.125.47.27</IpAddress>
 </BouncedMessageActivity>
</ActivityItems>

 

Element Name	Description
BouncedMessageActivity	The element containing all the bounce information. This is a repeating element, one for each bounce event for the specified day.
Category	A general category of the bounce.
CategoryCode	A unique code that identifies the category of the bounce.
Details	The detailed bounce message.

 

Bounce Categories

Please remove all bounces of type 10 and 30. Failure to do so may negatively impact your inbox performance with the various ISPs.

 

Category	Category Code	Description
Undetermined	1	The response text could not be identified.
Invalid Recipient	10	The recipient is invalid.
Soft Bounce	20	The message soft bounced.
DNS Failure	21	The message bounced due to a DNS failure.
Mailbox Full	22	The message bounced due to the remote mailbox being over quota.
Too Large	23	The message bounced because it was too large for the recipient.
Timeout	24	The message timed out.
Admin Failure	25	The message was failed by configured policies.
Generic Bounce: No RCPT	30	No recipient could be determined for the message.
Generic Bounce	40	The message failed for unspecified reasons.
Mail Block	50	The message was blocked by the receiver.
Spam Block	51	The message was blocked by the receiver as coming from a known spam source.
Spam Content	52	The message was blocked by the receiver as spam.
Prohibited Attachment	53	The message was blocked by the receiver because it contained an attachment.
Relay Denied	54	The message was blocked by the receiver because relaying is not allowed.
Transient Failure	70	Message transmission has been temporarily delayed.
Invalid Email Syntax	110	The message has a malformed/invalid email address.
Hardbounce Suppression	130	The message is a known-bad email address and has hard-bounces with a category 10 or 30 in the past. It was suppressed from sending to protect IP reputation with the ISP.
Unsubscribe Suppression	131	The recipient of the message has unsubscribed from a message from your account in the past. It was suppressed from sending to protect your sending reputation.
Fbl Suppression	132	The recipient of the message has filed a spam complaint with your account in the past. It was suppressed from sending to protect your sending reputation.
Complainer Suppression	133	The recipient of the message is a known complainer. It was suppressed from sending to protect your sending reputation.
Domain Suppression	134	The recipient domain is not allowed. It was suppressed from sending to protect your sending reputation.
Role Suppression	135	The recipient address is not allowed. It was suppressed from sending to protect your sending reputation.

 

Unsubscribe Activity Response

<ActivityItems>
 <UnsubActivity>
  <RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>
  <IpAddress>128.234.11.12</IpAddress>
  <UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>
 </UnsubActivity>
</ActivityItems>

 

Element Name	Description
UnsubActivity	The element containing all the unsub information. This is a repeating element, one for each open event for the specified day.
UserAgent	The browser type (or email client) used to provide the event.
Microsite	Will be set to “true” if this event originated from a microsite version of an email message.

 

Spam Complaint Activity Response

<ActivityItems>
 <SpamComplaintActivity>
  <RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>
  <Isp>gmail.com</Isp>
 </SpamComplaintActivity>
</ActivityItems>

 

Element Name	Description
SpamComplaintActivity	The element containing the Spam Complaint information. This is a repeating element, one for each complaint received for the specified day.
Isp	The domain part of the recipient’s email address.

 

Job Error Activity Response

<ActivityItems>
 <JobErrorActivity>
  <RequestId>t25710-9540c8d8-aa5d-44d7-a9ef-a334072df515</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <Timestamp>2010-09-14T13:20:36.994-04:00</Timestamp>
  <JobError>
   <ErrorCode>Transfer Error</ErrorCode>
   <ErrorMessage>AmazonClientException retrieving file: s3://mycompany/myfile.txt - The specified key does not exist.</ErrorMessage>
  </JobError>
 </JobErrorActivity>
</ActivityItems>

 

Element Name	Description
JobErrorActivity	The element containing theJob Error information. This is a repeating element, one for each job that failed to be processed for the specified day.
JobError	A repeating element, one for each error that occurred.
ErrorCode	A general error code for the failure.
ErrorMessage	A detailed error description.

 

Render Error Activity Response

<ActivityItems>
 <RenderErrorActivity>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <RenderErrors>
   <RenderError>
    <ErrorCode>Template merge exception</ErrorCode>
    <ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>
   </RenderError>
  </RenderErrors>
 </RenderErrorActivity>
</ActivityItems>

 

Element Name	Description
RenderErrorActivity	The element containing the error information regarding the rendering of an email message. This is a repeating element, one for each email that failed to be rendered for the specified day.
Error Code	A general error code for the failure.
ErrorMessage	A detailed error description.

 

Mobile Push Examples

Push Delivery

<ActivityItems>
 <DeliveredMobilePushActivity>
  <RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <DeviceId>123456789</DeviceId>
  <Service>APNS</Service>
  <ApplicationId>12345</ApplicationId>
  <Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>
  <PushDeliveryService>AWS Pinpoint</PushDeliveryService>
 </DeliveredMobilePushActivity>
</ActivityItems>

 

Push Delivery Failure

<ActivityItems>
 <BouncedMobilePushActivity>
  <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <DeviceId>12345678</DeviceId>
  <Service>APNS</Service>
  <ApplicationId>12345</ApplicationId>
  <Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>
  <Category>AWS Pinpoint Category, such as "TRANSIENT_FAILURE"</Category>
  <Details>A temporary error occurred. MessageGears will attempt to deliver the message again later.</Details>
  <PushDeliveryService>AWS Pinpoint</PushDeliveryService>
 </BouncedMobilePushActivity>
</ActivityItems>

 

The possible values for Category and Details are:

 

Category	Details
TRANSIENT_FAILURE	A temporary error occurred. MessageGears will attempt to deliver the message again later.
FAILURE_PERMANENT	An error occurred when delivering the message to the endpoint. MessageGears won’t attempt to send the message again.
TIMEOUT	The message couldn’t be sent within the timeout period.
DAILY_CAP	The endpoint has received the maximum number of messages it can receive within a 24-hour period.
THROTTLED	MessageGears throttled sending to this endpoint.
EXPIRED	The endpoint address is expired.
SERVICE_FAILURE	A service-level failure prevented MessageGears from delivering the message.
JOB_CANCELLED	The job has been cancelled

 

Push Render Error

<ActivityItems>
 <RenderErrorMobilePushActivity>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <DeviceId>12345678</DeviceId>
  <Service>APNS</Service>
  <ApplicationId>12345</ApplicationId>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <RenderErrors>
   <RenderError>
    <ErrorCode>Template merge exception</ErrorCode>
    <ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>
   </RenderError>
  </RenderErrors>
 </RenderErrorMobilePushActivity>
</ActivityItems>

 

SMS Examples

SMS Delivery

SMS Delivery confirmations detail the delivery details for each outbound message. Any unsuccessful message transmissions will result in a delivery failure (see below):

 

<ActivityItems>
 <DeliveredSmsActivity>
  <RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>123456789</DeviceId>
  <Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>
 </DeliveredSmsActivity>
</ActivityItems>

 

SMS Render Error

<ActivityItems>
 <RenderErrorSmsActivity>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>12345678</SmsAddress>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <RenderErrors>
   <RenderError>
    <ErrorCode>Template merge exception</ErrorCode>
    <ErrorMessage>Error on line 1, column 10 in BODY Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>
   </RenderError>
  </RenderErrors>
 </RenderErrorSmsActivity>
</ActivityItems>

 

SMS Delivery Failure

<ActivityItems>
 <BouncedSmsActivity>
  <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>12345678</SmsAddress>
  <Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>
  <Category>Sms Failure category, such as "INVALID_ADDRESS"</Category>
  <Details>The phone number you have attempted to send to is not valid or unrecognizable to our system.</Details>
 </BouncedSmsActivity>
</ActivityItems>

 

The possible values for Category and Details are:

 

Category	Details
INVALID_ADDRESS	The phone number you have attempted to send to is not valid or unrecognizable to our system
INTERNATIONAL_SENDING_PROHIBITED	International message sending is not enabled for your account. Please contact support to send to this number
ADDRESS_BLOCKED	The message could not be sent from this OriginationNumber to the destination address
INVALID_CONTENT	This content is unable to be sent as an SMS message
SERVICE_FAILURE	A service-level failure prevented MessageGears from delivering the message
JOB_CANCELLED	The job has been cancelled

 

SMS Inbound Message

<ActivityItems>
 <InboundSmsActivity>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>12345678</SmsAddress>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <To>12345</To>
  <InboundMessageType>STOP</InboundMessageType>
  <InboundMessage>The inbound message sent from the recipient, such as "STOP", "HELP", or a Keyword</InboundMessage>
 </InboundsmsActivity>
</ActivityItems>

 

Engage Examples

Context Data Hit

Context Data Hit events are created for requests to the Engage API that successfully return records. For multi-key requests, an event is generated for each requested record that was found. For requests sent using our Message product, a RequestId will be included. Additionally, for Message requests, a CorrelationId and RecipientId will also be included if they were present.

 

<ActivityItems>
 <ContextHitActivity>
 <Timestamp>2020-09-22T16:59:39Z</Timestamp>
 <AccountId>23295228</AccountId>
 <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
 <CorrelationId>Your Correlation Id</CorrelationId>
 <ActivityId>496517a3-1687-4d95-1011-ccd93ff7f540</ActivityId>
 <RecipientId>Your Recipient Id</RecipientId>
 <IpAddress>1.2.3.4</IpAddress>
 <Vendor>2</Vendor>
 <Prefix>DEMO2</Prefix>
 <RecordId>DEMO2-ofYlGLFP9e5HfcfI40l6TFoJtouGecQIr8nT</RecordId>
 <RecordSize>4107</RecordSize>
 <CreateTimestamp>2020-09-09T16:38:10Z</CreateTimestamp>
 <UpdateTimestamp>2020-09-09T16:38:10Z</UpdateTimestamp>
 </ContextHitActivity>
</ActivityItems>

 

Context Data Miss

Context Data Miss events are created for requests to the Engage API that fail to return records. For multi-key requests, an event is generated for each requested record that was not found. For requests sent using our Message product, a RequestId will be included. Additionally, for Message requests, a CorrelationId and RecipientId will also be included if they were present.

 

<ActivityItems>
 <ContextHitActivity>
 <Timestamp>2020-09-22T16:59:39Z</Timestamp>
 <AccountId>23295228</AccountId>
 <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
 <CorrelationId>Your Correlation Id</CorrelationId>
 <ActivityId>496517a3-1687-4d95-1011-ccd93ff7f540</ActivityId>
 <RecipientId>Your Recipient Id</RecipientId>
 <IpAddress>1.2.3.4</IpAddress>
 <Vendor>2</Vendor>
 <Prefix>DEMO2</Prefix>
 <RecordId>DEMO2-ofYlGLFP9e5HfcfI40l6TFoJtouGecQIr8nT</RecordId>
 </ContextHitActivity>
</ActivityItems>