API Reference – Reporting API – messagesFailed()

Reporting API Method Documentation

©2009-2014 SocketLabs, Inc., Version 1.9, Last Edit: October 24, 2014

messagesFailed

Synopsis:

Returns a list of email messages that failed during the delivery process due to either temporary or permanent errors.

Recommended Usage:

The messagesFailed method is deprecated in favor of the Notification API whenever possible. If the Notification API cannot be used, the messagesFailed method is useful for monitoring deliverability issues with a mail stream.

The failures retrieved by this method include both synchronous and asynchronous failures (bounces). Each entry returned by this API represents a single failure, and includes failure codes that explain the specific failure, as enumerated in the following KB article: https://support.socketlabs.com/kb/123. Please note, sometimes temporary failures are referred to as soft failures and permanent failures are referred to as hard failures. The terms are interchangeable. The SocketLabs Email On-Demand service marks failures as permanent if it believes that future delivery to that address is impossible. i.e. We received an “invalid address” response from the recipient’s mail server. These addresses should be corrected or removed from your list. The API marks failures as temporary if we believe that you many have luck delivering to that address in the future. i.e. The target mailbox was full.

The messagesFailed method can be used to record and monitor whether recipients are receiving mail, and possibly remove them from future mailings or handle delivery differently based on the permanent and temporary errors observed. For example, if a failed message returns an error stating that it no longer exists, that message’s recipient address should be removed from future mailings. However, if a failed message returns an error stating that there was some kind of network connection issue, it may be worth trying again later or monitoring whether the error persists; eventually removing that recipient’s address from future mailings if the errors cannot be resolved.

Request Information

URL:

https://api.socketlabs.com/v1/messagesFailed

Response Format Types:

JSON, JSONP, XML or CSV

HTTP Method:

GET

Request Parameters:

serverId
Specifies the server ID to query. For more information see this overview on using the Server ID.
type
Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
count
(Optional) Specifies the number of records to return in the result set. If this parameter is not specified it will default to 500. 500 is the maximum number of records that you may retrieve in one call. You can use this parameter in combination with the index parameter to pull down multiple “pages” of data making it possible to retrieve more than 500 records with multiple calls.
endDate
(Optional) Refers to the date and time that the outbound message failed. Specifies the ending date and time of the records to return. The value should be formatted as yyyy-mm-dd hh:mm:ss. If the time is omitted it will default to 00:00:00.
index
(Optional) Specifies the zero based index of the first record to return from the result set.
mailingId
(Optional) Only records matching the specified mailingId will be returned. For more information see this overview on using Mailing ID and Message ID.
messageId
(Optional) Only records matching the specified messageId will be returned. For more information see this overview on using Mailing ID and Message ID.
startDate
(Optional) Refers to the date and time that the outbound message failed. Specifies the starting date and time of the records to return. The value should be formatted as yyyy-mm-dd hh:mm:ss. If the time is omitted it will default to 00:00:00.
timeZone
(Optional) Specifies the timeZone offset that will be used by the API. For more information see this overview on using timezone data.

Example Request:

https://api.socketlabs.com/v1/messagesFailed?serverId=0001&type=xml

Response Data Structures

Response Data Structure (JSON):

{
    "timestamp": "Datetime",
    "totalCount": "Integer",
    "totalPages": "Integer",
    "page": "Integer",
    "count": "Integer",
    "collection": [
        {
            "ServerId": "Integer",
            "DateTime": "Datetime",
            "MessageId": "String",
            "MailingId": "String",
            "ToAddress": "String",
            "FromAddress": "String",
            "FailureType": "Integer",
            "FailureCode": "Integer",
            "Reason": "String."
        },
    ],
}

Response Data Structure (XML):

<response>
    <timestamp>Datetime</timestamp>
    <totalCount>Integer</totalCount>
    <totalPages>Integer</totalPages>
    <page>Integer</page>
    <count>Integer</count>
    <collection>
        <item>
            <ServerId>Integer</ServerId>
            <DateTime>Datetime</DateTime>
            <MessageId>String</MessageId>
            <MailingId>String</MailingId>
            <ToAddress>String</ToAddress>
            <FromAddress>String</FromAddress>
            <FailureType>Integer</FailureType>
            <FailureCode>Integer</FailureCode>
            <Reason>String</Reason>
        </item>
    </collection>
</response>

Response Data Structure (CSV):

Data columns in the CSV format are in the following order:

ServerId,DateTime,MessageId,MailingId,ToAddress,FromAddress,FailureType,FailureCode,Reason

Response Parameters

count
The number of failure entries in this page of data.
page
The current page of data returned by the query.
timestamp
The date and time of the API request.
totalCount
This field is deprecated, and should return as 0.
totalPages
This field is deprecated, and should return as 0.
collection.item.DateTime
The date and time that the failure occurred.
collection.item.FailureCode
A number representing the type of failure that occurred, as documented here: https://support.socketlabs.com/kb/123
collection.item.FailureType
Valid values are {0,1,2} and they represent soft/temporary failures, hard/permanent failures, and suppressions respectively.
collection.item.FromAddress
The sender of the message in question.
collection.item.MailingId
The X-xsMailingId header value of the message in question.
collection.item.MessageId
The X-xsMessageId header value of the message in question.
collection.item.Reason
A string describing the reason for the message delivery failure.
collection.item.ServerId
The ID of the server being queried.
collection.item.ToAddress
The recipient of the message in question.

Response Examples

Example Response (JSON):

{
    "timestamp": "1368647491557",
    "totalCount": 0,
    "totalPages": 0,
    "page": 1,
    "count": 1,
    "collection": [
        {
            "ServerId": 0001,
            "DateTime": "1361368985000",
            "MessageId": "",
            "MailingId": "",
            "ToAddress": "[email protected]",
            "FromAddress": "[email protected]",
            "FailureType": 0,
            "FailureCode": 4003,
            "Reason": "500 5.4.0 System rule action set to fail connection."
        },
    ],
}

Example Response (XML):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<response>
    <timestamp>2013-05-15T19:50:15.9963663Z</timestamp>
    <totalCount>0</totalCount>
    <totalPages>0</totalPages>
    <page>1</page>
    <count>1</count>
    <collection>
        <item>
            <ServerId>0001</ServerId>
            <DateTime>2013-02-20T14:03:05Z</DateTime>
            <MessageId></MessageId>
            <MailingId></MailingId>
            <ToAddress>[email protected]</ToAddress>
            <FromAddress>[email protected]</FromAddress>
            <FailureType>0</FailureType>
            <FailureCode>4003</FailureCode>
            <Reason>500 5.4.0 System rule action set to fail connection.</Reason>
        </item>
    </collection>
</response>

Example Response (CSV):

ServerId,DateTime,MessageId,MailingId,ToAddress,FromAddress,FailureType,FailureCode,Reason
0001,"""2/20/2013 2:03:05 PM +00:00""",,,[email protected],[email protected],0,4003,500 5.4.0 System rule action set to fail connection.

Customers Who Trust in SocketLabs

You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.

Why SocketLabs?

What Our Customers Are Saying!