Spam Complaints

When recipients of your messages press “Spam” button, Mailgun receives those complaints from ESPs (email service providers).

Mailgun can notify your application every time a recipient flags your message as spam.

This API allows you to programmatically download the list of users who have complained and “clear” those events.

GET /<domain>/complaints

Fetches the list of complaints.

Parameter	Description
limit	Maximum number of records to return. (100 by default)
skip	Number of records to skip. (0 by default)

GET /<domain>/complaints/<address>

Fetches a single spam complaint by a given email address. This is useful to check if a particular user has complained.

DELETE /<domain>/complaints/<address>

Removes a given spam complaint.

POST /<domain>/complaints

Adds an address to the complaints table.

Parameter	Description
address	Valid email address

Examples

Fetch the full list of all recipients who have pressed their “Spam” buttons:

def get_complaints
  RestClient.get "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/complaints"
end

Response JSON is shown below. Notice the following:

• There was only one user who clicked “Spam” button.
• According to count value, he clicked twice.
• created_at indicates the time when it happend.

{
  "total_count": 2,
  "items": [
    {
      "count": 1,
      "created_at": "Wed, 15 Feb 2012 11:19:55 GMT",
      "address": "ev@mailgun.net"
    },
    {
      "count": 2,
      "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
      "address": "romanto@profista.com"
    }
  ]
}

Now lets check if romanto@profista.com ever complained:

def check_user_complaints
  RestClient.get("https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
                 "@api.mailgun.net/v2/samples.mailgun.org/complaints/"\
                 "romanto@profista.com"){|response, request, result| response }
end

Of course he did. The response:

{
  "complaint": {
    "count": 2,
    "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
    "address": "romanto@profista.com"
  }
}

Add a complaint to the table:

def add_complaint
  RestClient.post "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/complaints",
  :address => 'ev@mailgun.net'
end

The response

{
  "message": "Address has been added to the complaints table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all recipients who have pressed their “Spam” buttons:

public static ClientResponse GetComplaints() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org/" +
                               "complaints");
       return webResource.get(ClientResponse.class);
}

Response JSON is shown below. Notice the following:

• There was only one user who clicked “Spam” button.
• According to count value, he clicked twice.
• created_at indicates the time when it happend.

{
  "total_count": 2,
  "items": [
    {
      "count": 2,
      "created_at": "Wed, 15 Feb 2012 11:29:26 GMT",
      "address": "ev@mailgun.net"
    },
    {
      "count": 2,
      "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
      "address": "romanto@profista.com"
    }
  ]
}

Now lets check if romanto@profista.com ever complained:

public static ClientResponse CheckUserComplaint() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org/" +
                               "complaints/romanto@profista.com");
       return webResource.get(ClientResponse.class);
}

Of course he did. The response:

{
  "complaint": {
    "count": 2,
    "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
    "address": "romanto@profista.com"
  }
}

Add a complaint to the table:

public static ClientResponse AddComplaint() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org/" +
                               "complaints");
       MultivaluedMapImpl formData = new MultivaluedMapImpl();
       formData.add("address", "ev@mailgun.net");
       return webResource.type(MediaType.APPLICATION_FORM_URLENCODED).
               post(ClientResponse.class, formData);
}

The response

{
  "message": "Address has been added to the complaints table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all recipients who have pressed their “Spam” buttons:

function get_complaints() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/complaints',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->send();
  return $request;
}

Response JSON is shown below. Notice the following:

• There was only one user who clicked “Spam” button.
• According to count value, he clicked twice.
• created_at indicates the time when it happend.

{
  "total_count": 2,
  "items": [
    {
      "count": 4,
      "created_at": "Wed, 15 Feb 2012 11:43:32 GMT",
      "address": "ev@mailgun.net"
    },
    {
      "count": 2,
      "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
      "address": "romanto@profista.com"
    }
  ]
}

Now lets check if romanto@profista.com ever complained:

function check_user_complaints() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/'
                    .'complaints/romanto@profista.com',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->send();
  return $request;
}

Of course he did. The response:

{
  "complaint": {
    "count": 2,
    "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
    "address": "romanto@profista.com"
  }
}

Add a complaint to the table:

function add_complaint() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/'
                    .'complaints',
                    HttpRequest::METH_POST);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->setPostFields(array('address' => 'ev@mailgun.net'));
  $request->send();
  return $request;
}

The response

{
  "message": "Address has been added to the complaints table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all recipients who have pressed their “Spam” buttons:

def get_complaints():
    r = requests.\
        get("https://api.mailgun.net/v2/samples.mailgun.org/"\
            "complaints",
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"))
    return r

Response JSON is shown below. Notice the following:

• There was only one user who clicked “Spam” button.
• According to count value, he clicked twice.
• created_at indicates the time when it happend.

{
  "total_count": 1,
  "items": [
    {
      "count": 2,
      "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
      "address": "romanto@profista.com"
    }
  ]
}

Now lets check if romanto@profista.com ever complained:

def check_user_complaints():
    r = requests.\
        get("https://api.mailgun.net/v2/samples.mailgun.org/"\
            "complaints/romanto@profista.com",
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"))
    return r

Of course he did. The response:

{
  "message": "No spam complaints found for this address"
}

Add a complaint to the table:

def add_complaint():
    r = requests.\
        post("https://api.mailgun.net/v2/samples.mailgun.org/"\
             "complaints",
             auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
             data={'address': 'ev@mailgun.net'})
    return r

The response

{
  "message": "Address has been added to the complaints table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all recipients who have pressed their “Spam” buttons:

public static RestResponse GetComplaints() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.Resource = "{domain}/complaints";
       return client.Execute(request);
}

Response JSON is shown below. Notice the following:

• There was only one user who clicked “Spam” button.
• According to count value, he clicked twice.
• created_at indicates the time when it happend.

{
  "total_count": 2,
  "items": [
    {
      "count": 3,
      "created_at": "Wed, 15 Feb 2012 11:35:24 GMT",
      "address": "ev@mailgun.net"
    },
    {
      "count": 2,
      "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
      "address": "romanto@profista.com"
    }
  ]
}

Now lets check if romanto@profista.com ever complained:

public static RestResponse CheckUserComplaints() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.Resource = "{domain}/complaints/romanto@profista.com";
       return client.Execute(request);
}

Of course he did. The response:

{
  "complaint": {
    "count": 2,
    "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
    "address": "romanto@profista.com"
  }
}

Add a complaint to the table:

public static RestResponse AddComplaint() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.Resource = "{domain}/complaints";
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.AddParameter("address", "ev@mailgun.net");
       request.Method = Method.POST;
       return client.Execute(request);
}

The response

{
  "message": "Address has been added to the complaints table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all recipients who have pressed their “Spam” buttons:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 -G \
    https://api.mailgun.net/v2/samples.mailgun.org/complaints

Response JSON is shown below. Notice the following:

• There was only one user who clicked “Spam” button.
• According to count value, he clicked twice.
• created_at indicates the time when it happend.

{
  "total_count": 2,
  "items": [
      {
          "count": 6,
          "created_at": "Wed, 15 Feb 2012 12:35:53 GMT",
          "address": "ev@mailgun.net"
      },
      {
          "count": 2,
          "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
          "address": "romanto@profista.com"
      }
  ]
}

Now lets check if romanto@profista.com ever complained:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 -G \
    https://api.mailgun.net/v2/samples.mailgun.org/complaints/romanto@profista.com

Of course he did. The response:

{
  "complaint": {
      "count": 2,
      "created_at": "Tue, 15 Nov 2011 08:25:11 GMT",
      "address": "romanto@profista.com"
  }
}

Add a complaint to the table:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 \
    https://api.mailgun.net/v2/samples.mailgun.org/complaints \
    -F address='ev@mailgun.net'

The response:

{
  "message": "Address has been added to the complaints table",
  "address": "ev@mailgun.net"
}