AccountActivity v3.1

AccountActivity is used to retrieve a file containing all of the activity data for a single day for an activity type. If you need to retrieve your data more frequently that once a day, you should considering using the “Event Feed” which will allow you to consume the same activity/events as they occur. This API differs from others in that it “streams” back a large binary byte array. It can be invoked via using utilities like WGET or CURL, or you can write your code to retrieve the data. It’s important to remember that these files can be large and often will be too large to fit into memory all at once. Write your code so that the file is streamed to disk or to a database for processing.

XSD Location

For a detailed list of all response values, refer to the XSD file below.

https://api.messagegears.net/3.1/WebService?Action=XSD

Deprecated Versions

v3.0 (unchanged in 3.1)

Input Parameters

Parameter	Description
Action	AccountActivity
AccountId	The MessageGears account id to which this item belongs.
ApiKey	A secret key only known by you. Keep this key confidential.
ActivityDate	The date of the activity that is being requested. This field must be in the form of yyyy-MM-dd (example: 2010-12-31).
ActivityType	One of the following strings must be provided: OPENS, CLICKS, BOUNCES, DELIVERIES, SPAM_COMPLAINTS, RENDER_ERRORS, UNSUBSCRIBES, JOB_ERRORS, MOBILE_PUSH_DELIVERIES, MOBILE_PUSH_CLICKS, MOBILE_PUSH_DELIVERY_FAILURES, MOBILE_PUSH_RENDER_ERRORS, SMS_CLICKS, SMS_DELIVERIES, SMS_DELIVERY_FAILURES, SMS_RENDER_ERRORS, SMS_INBOUNDS
UseCompression	Set whether the data returned is compressed in .zip format. Set to TRUE to download the data in a compressed format (this is the suggested method)

Response Values

Common Response Elements (present for all activity types)

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.
CorrelationId	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.
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.

Click the Activity Types below to view more about each activity response, including example responses and complete response elements.

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.
Erro Code	A general error code for the failure.
ErrorMessage	A detailed error description.

REST

Request

https://api.messagegears.net/3.1/WebService  
?Action=AccountActivity  
&AccountId=123456789  
&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd  
&ActivityDate=2010-12-31  
&ActivityType=BOUNCES

See above for examples of each response by ActivityType

Java SDK

Click here for more information on using the MessageGears Java SDK

package com.messagegears.sdk.examples;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.util.Calendar;
import java.util.Date;

import com.messagegears.sdk.v3_1.BouncedMessageActivity;
import com.messagegears.sdk.v3_1.ClickActivity;
import com.messagegears.sdk.v3_1.DeliveredMessageActivity;
import com.messagegears.sdk.v3_1.JobErrorActivity;
import com.messagegears.sdk.v3_1.OpenActivity;
import com.messagegears.sdk.v3_1.RenderErrorActivity;
import com.messagegears.sdk.v3_1.SpamComplaintActivity;
import com.messagegears.sdk.v3_1.UnsubActivity;
import com.messagegears.sdk.MessageGearsClient;
import com.messagegears.sdk.MessageGearsListener;
import com.messagegears.sdk.MessageGearsProperties;
import com.messagegears.sdk.activity.MessageGearsActivityFileProcessor;
import com.messagegears.sdk.model.ActivityType;
import com.messagegears.sdk.model.request.AccountActivityRequest;
import com.messagegears.sdk.output.ScreenWriter;

public class ActivityFileExample implements MessageGearsListener {

    public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "your MessageGears Account Id";
    public static final String MY_MESSAGEGEARS_API_KEY = "your MessageGears API Key";
    public static Date activityDate;

    public static void main(String[] args) {
        // Create the AWS properties object
        MessageGearsProperties props = new MessageGearsProperties();
        props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);
        props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);

        // Create the main client object
        MessageGearsClient client = new MessageGearsClient(props);

        // Create an object of this listener class and process
        ActivityFileExample listener = new ActivityFileExample();

        // Create a file processor object, and request processing
        MessageGearsActivityFileProcessor processor = new MessageGearsActivityFileProcessor(listener);

        // Set date to yesterday.
        Calendar calendar = Calendar.getInstance();
        calendar.add(Calendar.DAY_OF_YEAR, -1);
        activityDate = calendar.getTime();

        AccountActivityRequest request = new AccountActivityRequest();
        request.setDate(activityDate);

        // Download the activity files and process them.
        for (ActivityType activityType : ActivityType.values()) {
            try {
                request.setActivityType(activityType);
                String downloadedFileName = client.accountActivity(request);
                FileInputStream inputStream = new FileInputStream(new File(downloadedFileName));
                processor.process(inputStream, activityType);
            } catch (FileNotFoundException fnfe) {
                System.err.println("Error processing activity of type: " + activityType.name());
                System.err.println("FileNotFoundException: " + fnfe.getMessage());
            }
        }
    }

    public void onOpen(OpenActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onClick(ClickActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onBounce(BouncedMessageActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onDelivery(DeliveredMessageActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onSpamComplaint(SpamComplaintActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onJobError(JobErrorActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onRenderError(RenderErrorActivity activity) {
        ScreenWriter.print(activity);
    }

    public void onUnsub(UnsubActivity activity) {
        ScreenWriter.print(activity);
    }
}

C# SDK

Click here for more information on using the MessageGears .Net SDK

using System;
using MessageGears;
using MessageGears.Model;
using MessageGears.Model.Generated;

namespace MessageGears.Examples
{
    public class ActivityFileExample : MessageGearsListener
    {
        public const String MY_MESSAGEGEARS_ACCOUNT_ID = "your MessageGears Account Id";
        public const String MY_MESSAGEGEARS_API_KEY = "your MessageGears API Key";
        public static DateTime activityDate = System.DateTime.Today.AddDays(-1);

        public static void Main()
        {
            // Create the AWS properties object
            MessageGearsProperties props = new MessageGearsProperties();
            props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;
            props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;

            // Create the main client object
            MessageGearsClient client = new MessageGearsClient(props);

            // Create an object of this listener class and process
            ActivityFileExample listener = new ActivityFileExample();

            // Create a file processor object, and request processing
            MessageGearsActivityFileProcessor processor = new MessageGearsActivityFileProcessor(listener);

            // Download the activity files and process them.
            processor.process(client.AccountActivity(activityDate, ActivityType.BOUNCES));
            processor.process(client.AccountActivity(activityDate, ActivityType.CLICKS));
            processor.process(client.AccountActivity(activityDate, ActivityType.DELIVERIES));
            processor.process(client.AccountActivity(activityDate, ActivityType.JOB_ERRORS));
            processor.process(client.AccountActivity(activityDate, ActivityType.OPENS));
            processor.process(client.AccountActivity(activityDate, ActivityType.RENDER_ERRORS));
            processor.process(client.AccountActivity(activityDate, ActivityType.SPAM_COMPLAINTS));
            processor.process(client.AccountActivity(activityDate, ActivityType.UNSUBSCRIBES));
        }

        public void OnOpen(OpenActivity activity)
        {
            Console.WriteLine("***** Open Event Received");
        }

        public void OnClick(ClickActivity activity)
        {
            Console.WriteLine("***** Click Event Received: " + activity.ActivityId);
        }

        public void OnBounce(BouncedMessageActivity activity)
        {
            Console.WriteLine("***** Bounce Event Received");
        }

        public void OnDelivery(DeliveredMessageActivity activity)
        {
            Console.WriteLine("***** Delivery Event Received");
        }

        public void OnSpamComplaint(SpamComplaintActivity activity)
        {
            Console.WriteLine("***** Spam Complaint Event Received");
        }

        public void OnJobError(JobErrorActivity activity)
        {
            Console.WriteLine("***** Job Error Event Received");
        }

        public void OnRenderError(RenderErrorActivity activity)
        {
            Console.WriteLine("***** Render Error Event Received");
        }

        public void OnUnsub(UnsubActivity activity)
        {
            Console.WriteLine("***** Unsub Event Received");
        }
    }
}

XSD Location​

Input Parameters​

Response Values​

Click Activity Response​

Open Activity Response​

Delivery Activity Response​

Bounce Activity Response​

Bounce Categories​

Unsubscribe Activity Response​

Spam Complaint Activity Response​

Job Error Activity Response​

Render Error Activity Response​

Programming Examples​

REST​

Java SDK​

C# SDK​