BulkJobSummary v3.1

BulkJobSummary is used to check the status of an individual bulk job. A typical use case would be for a dashboard application to poll this API for any active bulk jobs in order to update counters, gauges, and dials on a user interface.

Prior Versions

Input Parameters

Parameter Description
Action BulkJobSummary
AccountId The MessageGears account id to which this item belongs.
ApiKey A secret key only known by you. Keep this key confidential.
BulkJobRequestId The Request Id of the bulk job to be queried. You can supply this field or the BulkJobCorrelationId, but not both.
BulkJobCorrelationId The correlation Id of the bulk job to be queried. You can supply this field or the BulkJobRequestId, but not both. This value is provided by the user when the BulkJobSubmit API is called. Querying using this value can be very helpful when building BulkJobSubmit retry logic when and error occurs and you are not sure if the bulk job request was received successfully.

Response Values

Parameter Data Type Description
BulkJobRequestId String The Request Id of the bulk to be queried. This is simply a confirmation of the bulk job id that was submitted to the service.
Messages Integer The total number of email message that were submitted to the service for processing for both transactional and bulk jobs.
Clicks Integer The total number of trackable links that were clicked.
Opens Integer The total number of messages that were opened.
Bounces Integer The total number of messages that were confirmed as undelivered.
Deliveries Integer The total number of messages that were successfully delivered.
Unsubscribes Integer The total number of unsubscribe requests received. This includes any optional MessageGears "unsubscribe" links, as well as "list unsubscribe" headers.
SpamComplaints Integer The total number of times recipients clicked the “report spam” button, or sent their messages to the MessageGears abuse mailbox.
RenderErrors Integer The total number of messages that could not be delivered as a result of errors in the message content. This usually occurs when there is syntax error in the Freemarker or Velocity script (if any) contained in the message content.
BulkJobErrors String A list of errors experienced in attempting to process the bulk job. These are errors that were experiences after the request was received. Examples of this kind of error include errors retrieving the recipient data file, and errors with the XML content of the recipient data file. Usually, an error of this type prevents the entire job from being processed. The remedy is to simple fix the error and resubmit the entire job via the SendBulkJob API.
CorrelationId String The user-defined correlation id that was specified when the job was submitted. It should be a unique value that identifies the job in the customer’s system.

Programming Examples

Request

https://api.messagegears.net/3.1/WebService
?Action=BulkJobSummary
&AccountId=123456789
&ApiKey=8bb6118f8fd6935ad0876a3be34a717d32708ffd
&BulkJobRequestId=b23510-82279647-13fa-4930-8338-ec85988b6bed

Response

<BulkJobSummaryResponse>
    <RequestId>71d7261e-bbf7-487d-b201-6d3557370cd2</RequestId>
    <Result>REQUEST_SUCCESSFUL</Result>
    <BulkJobSummary>
        <BulkJobRequestId>b23510-82279647-13fa-4930-8338-ec85988b6bed</BulkJobRequestId>
        <CorrelationId>My Job Id</CorrelationId>
        <Messages>1000000</Messages>
        <Clicks>123231</Clicks>
        <Opens>152323</Opens>
        <Bounces>1283</Bounces>
        <Unsubsribes>0</Unsubsribes>
        <Deliveries>998121</Deliveries>
        <SpamComplaints>2</SpamComplaints>
        <RenderErrors>0</RenderErrors>
    </BulkJobSummary>
</BulkJobSummaryResponse>

Click here to see more details about using the MessageGears Java SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package com.messagegears.sdk.examples;
 
import com.messagegears.sdk.v3_1.BulkJobSummaryResponse;
import com.messagegears.sdk.MessageGearsClient;
import com.messagegears.sdk.MessageGearsProperties;
import com.messagegears.sdk.model.request.BulkJobSummaryRequest;
import com.messagegears.sdk.output.ScreenWriter;
 
public class BulkJobSummaryExample {
 
    public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
    public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
    public static final String MY_BULK_JOB_REQUEST_ID = "place your bulk job request id here";
 
    public static void main(String[] args) {
        // Create the properties object containing the necessary properties
        MessageGearsProperties props = new MessageGearsProperties();
        props.setMyMessageGearsAccountId(MY_MESSAGEGEARS_ACCOUNT_ID);
        props.setMyMessageGearsApiKey(MY_MESSAGEGEARS_API_KEY);
 
        // Create the MessageGears client object
        MessageGearsClient client = new MessageGearsClient(props);
 
        // Invoke the BulkJobSummary API
        BulkJobSummaryRequest request = new BulkJobSummaryRequest();
        request.setRequestId(MY_BULK_JOB_REQUEST_ID);
        BulkJobSummaryResponse response =  client.bulkJobSummary(request);
 
        // Print the result
        ScreenWriter.printResponse(response);
    }
}
package com.messagegears.sdk.examples;

import com.messagegears.sdk.v3_1.BulkJobSummaryResponse;
import com.messagegears.sdk.MessageGearsClient;
import com.messagegears.sdk.MessageGearsProperties;
import com.messagegears.sdk.model.request.BulkJobSummaryRequest;
import com.messagegears.sdk.output.ScreenWriter;

public class BulkJobSummaryExample {

    public static final String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
    public static final String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
    public static final String MY_BULK_JOB_REQUEST_ID = "place your bulk job request id here";

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

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

        // Invoke the BulkJobSummary API
        BulkJobSummaryRequest request = new BulkJobSummaryRequest();
        request.setRequestId(MY_BULK_JOB_REQUEST_ID);
        BulkJobSummaryResponse response =  client.bulkJobSummary(request);

        // Print the result
        ScreenWriter.printResponse(response);
    }
}

Click here to see more details about using the MessageGears .Net SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
using System;
using System.IO;
using MessageGears;
using MessageGears.Model;
using MessageGears.Model.Generated;
 
namespace MessageGears.Examples
{
    public class BulkJobSummaryExample
    {
        public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
        public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
        public const String MY_BULK_JOB_REQUEST_ID = "place your bulk job request id here";
 
        public static void Main ()
        {
            // Create the properties object containing the necessary properties
            MessageGearsProperties props = new MessageGearsProperties();
            props.MyMessageGearsAccountId = MY_MESSAGEGEARS_ACCOUNT_ID;
            props.MyMessageGearsApiKey = MY_MESSAGEGEARS_API_KEY;
 
            // Create the MessageGears client object
            MessageGearsClient client = new MessageGearsClient(props);
 
            // Invoke the BulkJobSummary API
            BulkJobSummaryResponse response =  client.BulkJobSummary(MY_BULK_JOB_REQUEST_ID);
 
            // Print the result
            client.PrintResponse(response);
        }
    }
}
using System;
using System.IO;
using MessageGears;
using MessageGears.Model;
using MessageGears.Model.Generated;

namespace MessageGears.Examples
{
	public class BulkJobSummaryExample
	{
		public const String MY_MESSAGEGEARS_ACCOUNT_ID = "place your MessageGears account id here";
		public const String MY_MESSAGEGEARS_API_KEY = "place your MessageGears api key here";
		public const String MY_BULK_JOB_REQUEST_ID = "place your bulk job request id here";

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

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

			// Invoke the BulkJobSummary API
			BulkJobSummaryResponse response =  client.BulkJobSummary(MY_BULK_JOB_REQUEST_ID);

  			// Print the result
 			client.PrintResponse(response);
 		}
 	}
}