API Reference – Reporting API – messagesFblReported()

Reporting API Method Documentation

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

messagesFblReported

Synopsis:

Retrieve a list of feedback loop reports, which represent spam complaints against previously delivered messages.

Recommended Usage:

The messagesFblReported method is deprecated in favor of the Notification API whenever possible. If the Notification API cannot be used, the messagesFblReported method is useful for tracking which messages have generated feedback loop reports.The feedback loop system is a way for ISPs to provide feedback on messages sent to recipients on their network. Most typically these are triggered as the result of a recipient clicking on the “report as spam” button in their email client; however, feedback loops can also report other types of information. The “type” column in the result set will indicate the nature of the feedback, such as “abuse”. It is important that you remove email addresses from your list that have filed a complaint report against you. This can easily be accomplished by using the FeedbackLoops method to retrieve these addresses and then employ your own process to remove these from your list.

Request Information

URL:

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

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 feedback loop was reported. 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  feedback loop was reported. 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/messagesFblReported?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",
            "OriginalRecipient": "String",
            "FromAddress": "String",
            "UserAgent": "String",
            "Type": "String",
            "Isp": "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>
            <OriginalRecipient>String</OriginalRecipient>
            <FromAddress>String</FromAddress>
            <UserAgent>String</UserAgent>
            <Type>String</Type>
            <Isp>String</Isp>
        </item>
    </collection>
</response>

Response Data Structure (CSV):

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

ServerId,DateTime,MessageId,MailingId,OriginalRecipient,FromAddress,UserAgent,Type,Isp

Response Parameters

count
The number of 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 report occurred.
collection.item.FromAddress
The sender of the message in question.
collection.item.Isp
The name of the ISP that generated the feedback loop as detected from the value in the UserAgent field. Currently several major ESPs are detected in this manner, with other values set to ‘Other’.
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.OriginalRecipient
The original recipient of the message in question.
collection.item.ServerId
The ID of the server being queried.
collection.item.Type
The type of feedback being provided. Possible responses and their meanings are:

  • abuse – Spam or some other kind of email abuse
  • dkim – A DKIM signature verification error
  • fraud – Indicates some kind of fraud or phishing activity
  • virus – Report of a virus found in the originating message
  • other – Any other feedback that doesn’t match another type
collection.item.UserAgent
The self-reported name of the agent that generated the feedback loop.

Response Examples

Example Response (JSON):

{
    "timestamp": "1368648699696",
    "totalCount": 0,
    "totalPages": 0,
    "page": 1,
    "count": 1,
    "collection": [
        {
            "ServerId": 0001,
            "DateTime": "1360889328000",
            "MessageId": "4745222",
            "MailingId": "Campaign7",
            "OriginalRecipient": "[email protected]",
            "FromAddress": "[email protected]",
            "UserAgent": "Hotmail",
            "Type": "abuse",
            "Isp": "Hotmail"
        },
    ],
}

Example Response (XML):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<response>
    <timestamp>2013-05-15T20:11:59.2906667Z</timestamp>
    <totalCount>0</totalCount>
    <totalPages>0</totalPages>
    <page>1</page>
    <count>1</count>
    <collection>
        <item>
            <ServerId>0001</ServerId>
            <DateTime>2013-02-15T00:48:48Z</DateTime>
            <MessageId>4745222</MessageId>
            <MailingId>Campaign7</MailingId>
            <OriginalRecipient>[email protected]</OriginalRecipient>
            <FromAddress>[email protected]</FromAddress>
            <UserAgent>Hotmail</UserAgent>
            <Type>abuse</Type>
            <Isp>Hotmail</Isp>
        </item>
    </collection>
</response>

Example Response (CSV):

ServerId,DateTime,MessageId,MailingId,OriginalRecipient,FromAddress,UserAgent,Type,Isp
0001,"""2/15/2013 12:48:48 AM +00:00""",4745222,Campaign7,[email protected],[email protected],Hotmail,abuse,Hotmail

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!