Suppressions

Mailgun keeps three lists of addresses it blocks the delivery to: bounces, unsubscribes and complaints. These lists are populated automatically as Mailgun detects undeliverable addresses you try to send to and as recipients unsubscribe from your mailings or mark your emails as a spam (for ESPs that provide FBL). You can also add/remove addresses from any of these lists using the API.

Note

This is the documentation for the new Suppressions API. The documentation for the previous version (/v2) will temporarily be available here: bounces, unsubscribes, complaints.

Bounces

Bounce list stores events of delivery failures due to permanent recipient mailbox errors such as non-existent mailbox. Soft bounces (for example, mailbox is full) and other failures (for example, ESP rejects an email because it thinks it is spam) are not added to the list.

Subsequent delivery attempts to an address found in a bounce list are prevented to protect your sending reputation.

Mailgun can notify your application every time a message bounces via a bounce webhook.

View all bounces

GET /<domain>/bounces

Paginate over a list of bounces for a domain.

Note

Via this API method bounces are returned in the alphabetical order. If you wish to poll for the recently occurred bounces, please consider using the Events API.

Parameter Description
limit Maximum number of records to return (optional, default: 100, max: 10000)

Example:

curl -s --user 'api:YOUR_API_KEY' -G \
  https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getBounces() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/bounces")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->get("$domain/bounces");
def get_bounces():
    return requests.get(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces",
        auth=("api", "YOUR_API_KEY"))
def get_bounces
  RestClient.get "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetBouncesChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetBounces ().Content.ToString ());
    }

    public static IRestResponse GetBounces ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "{domain}/bounces";
        return client.Execute (request);
    }

}
func GetBounces(domain, apiKey string) (int, []mailgun.Bounce, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  total, bounces, err := mg.GetBounces(-1, -1)
  return total, bounces, err
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/${DOMAIN}/bounces/`, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "items":
    [
      {
        "address": "alice@example.com",
        "code": "550",
        "error": "No such mailbox",
        "created_at": "Fri, 21 Oct 2011 11:02:55 GMT"
      },
      ...
    ],
  "paging":
    {
      "first": <first page URL>,
      "next": <next page URL>,
      "previous": <previous page URL>,
      "last": <last page URL>
    }
}

View a single bounce

GET /<domain>/bounces/<address>

Fetch a single bounce event by a given email address. Useful to check if a given email address has bounced before.

Example:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces/foo@bar.com
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getSingleBounce() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/bounces/foo@bar.com")
                       .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';
$bounce = 'bob@example.com';

# Issue the call to the client.
$result = $mgClient->get("$domain/bounces/$bounce");
def get_bounce():
    return requests.get(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces/foo@bar.com",
        auth=("api", "YOUR_API_KEY"))
def get_bounce
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces"\
                 "/foo@bar.com"){|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetBounceChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetBounce ().Content.ToString ());
    }

    public static IRestResponse GetBounce ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "{domain}/bounces/foo@bar.com";
        return client.Execute (request);
    }

}
func GetBounce(domain, apiKey string) (mailgun.Bounce, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetSingleBounce("foo@bar.com")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/${DOMAIN}/bounces`, function (error, body) {
  console.log(body);
});

Expected responses:

200
{
  "address": "foo@bar.com",
  "code": "550",
  "error": "No such mailbox",
  "created_at": "Fri, 21 Oct 2011 11:02:55 GMT"
}
404
{
  "message": "Address not found in bounces table"
}

Add a single bounce

POST /<domain>/bounces

Add a bounce record to the bounce list. Updates the existing record if the address is already there.

Parameter Description
address Valid email address
code Error code (optional, default: 550)
error Error description (optional, default: empty string)
created_at Timestamp of a bounce event in RFC2822 format (optional, default: current time)

Example:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces \
    -F address='bob@example.com'
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode addBounce() throws UnirestException {

        HttpResponse <JsonNode> request =  Unirest.post("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/bounces")
            .basicAuth("api", API_KEY)
            .field("address", "bob@example.com")
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->post("$domain/bounces", array('address' => 'bob@example.com'));
def add_bounce():
    return requests.post(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces",
        auth=("api", "YOUR_API_KEY"),
        data={'address':'bob@example.com'})
def add_bounce
  RestClient.post("https://api:YOUR_API_KEY"\
                  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/bounces",
                  :address => 'bob@example.com')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddBounceChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (AddBounce ().Content.ToString ());
    }

    public static IRestResponse AddBounce ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "{domain}/bounces";
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.AddParameter ("address", "bob@example.com");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func AddBounce(domain, apiKey) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.AddBounce("bob@example.com", "550", "Undeliverable message error")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.post(`/${DOMAIN}/bounces`, {'address': 'bob@example.com'}, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "message": "Address has been added to the bounces table",
  "address": "bob@example.com"
}

Add multiple bounces

POST /<domain>/bounces, Content-Type: application/json

Add multiple bounce records to the bounce list in a single API call.

Request body is expected to be a valid JSON encoded string containing up to 1000 bounce records in the following format.

[
  {
    "address": "alice@example.com",
    "code": "550",
    "error": "Bounced",
    "created_at": "Thu, 13 Oct 2011 18:02:00 UTC"
  },
  {
    "address": "bob@example.com",
    "code": "550",
    "error": "Bounced"
  },
  {
    "address": "carol@example.com",
    "code": "550"
  },
  {
    "address": "dan@example.com"
  }
]

Fields within each individual bounce record are the same as for the “add a single bounce” API method, with the same defaults and optionality rules.

Note

The current versions of our language libraries do not support adding multiple bounces yet.

Expected response:

200
{
  "message": "4 addresses have been added to the bounces table"
}

Delete a single bounce

DELETE /<domain>/bounces/<address>

Clears a given bounce event. The delivery to the deleted email address resumes until it bounces again.

Expected response:

200
{
  "message": "Bounced address has been removed"
}

Delete an entire bounce list

DELETE /<domain>/bounces

Clears all bounced email addresses for a domain. Delivery to the deleted email addresses will no longer be suppressed.

Expected response:

200
{
  "message": "Bounced addresses for this domain have been removed"
}

Unsubscribes

Unsubscribe list stores email addresses of recipients who unsubscribed from your mailings by clicking a Mailgun generated unsubscribe link.

Mailgun allows you to quickly add “Unsubscribe me” feature to your outgoing emails without any programming on your end. You can enable this in your Control Panel under your domain settings.

Mailgun can notify your application every time a user unsubscribes via an unsubscribe webhook.

View all unsubscribes

GET /<domain>/unsubscribes

Paginate over a list of unsubscribes for a domain.

Note

Via this API method unsubscribes are returned in the alphabetical order. If you wish to poll for the recently occurred unsubscribes, please consider using the Events API.

Parameter Description
limit Number of records to return (optional, default: 100, max: 10000)

Example:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getUnsubscribes() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/unsubscribes")
            .basicAuth("api", API_KEY)
                   .asJson();

           return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->get("$domain/unsubscribes", array(
    'limit' => 5,
    'skip' => 10
));
def get_unsubscribes():
    return requests.get(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
        auth=("api", "YOUR_API_KEY"))
def get_unsubscribes
  RestClient.get "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetUnsubscribesChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetUnsubscribes ().Content.ToString ());
    }

    public static IRestResponse GetUnsubscribes ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "{domain}/unsubscribes";
        return client.Execute (request);
    }

}
func GetUnsubscribes(domain, apiKey string) (int, []mailgun.Unsubscribe, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetUnsubscribes(-1, -1)
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/${DOMAIN}/unsubscribes`, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "items":
    [
      {
        "address": "alice@example.com",
        "tag": "*",
        "created_at": "Fri, 21 Oct 2011 11:02:55 GMT"
      },
      ...
    ],
  "paging":
    {
      "first": <first page URL>,
      "next": <next page URL>,
      "previous": <previous page URL>,
      "last": <last page URL>
    }
}

View a single unsubscribe

GET /<domain>/unsubscribes/<address>

Fetch a single unsubscribe record. Can be used to check if a given address is present in the list of unsubscribed users.

Expected responses:

200
{
  "address": "alice@example.com",
  "tag": "*",
  "created_at": "Fri, 21 Oct 2011 11:02:55 GMT"
}
404
{
  "message": "Address not found in unsubscribers table"
}

Add a single unsubscribe

POST /<domain>/unsubscribes

Add an address to the unsubscribe table.

Parameter Description
address Valid email address
tag Tag to unsubscribe from, use * to unsubscribe an address from all domain’s correspondence (optional, default: *)
created_at Timestamp of an unsubscribe event in RFC2822 format (optional, default: current time)

Example:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes \
    -F address='bob@example.com' \
    -F tag='*'
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode addUnsubscribeAll() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/unsubscribes")
                       .basicAuth("api", API_KEY)
                       .field("address", "bob@example.com")
                   .field("tag", "*")
                   .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->post("$domain/unsubscribes", array(
    'address' => 'bob@example.com',
    'tag'     => '*'
));
def unsubscribe_from_all():
    return requests.post(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
        auth=("api", "YOUR_API_KEY"),
        data={'address':'bob@example.com', 'tag': '*'})
def unsubscribe_from_all
  RestClient.post "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
  :address => 'bob@example.com',
  :tag => '*'
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddUnsubscribeAllChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (UnsubscribeFromAll ().Content.ToString ());
    }

    public static IRestResponse UnsubscribeFromAll ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "{domain}/unsubscribes";
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.AddParameter ("address", "bob@example.com");
        request.AddParameter ("tag", "*");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func CreateUnsubscription(domain, apiKey string) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.Unsubscribe("bob@example.com", "*")
}

.. code-block:: node

var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.post(`/${DOMAIN}/unsubscribes`, {"address": 'bob@example.com', "tag":'*'}, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "message": "Address has been added to the unsubscribes table",
  "address": "bob@example.com"
}

Add multiple unsubscribes

POST /<domain>/unsubscribes, Content-Type: application/json

Add multiple unsubscribe records to the unsubscribe list in a single API call.

Request body is expected to be a valid JSON encoded string containing up to 1000 unsubscribe records in the following format.

[
  {
    "address": "alice@example.com",
    "tags": ["some tag"],
    "created_at": "Thu, 13 Oct 2011 18:02:00 UTC"
  },
  {
    "address": "bob@example.com",
    "tags": ["*"],
  },
  {
    "address": "carol@example.com"
  }
]

Fields within each individual unsubscribe record are the same as for the “add a single unsubscribe” API method, with the same defaults and optionality rules.

Note

The current versions of our language libraries do not support adding multiple unsubscribes yet.

Expected response:

200
{
  "message": "3 addresses have been added to the unsubscribes table"
}

Delete a single unsubscribe

DELETE /<domain>/unsubscribes/<address>

Remove an address from the unsubscribes list. If tag parameter is not provided, completely removes an address from the list.

Parameter Description
tag Specific tag to remove (optional)

Expected response:

200
{
  "message": "Unsubscribe event has been removed"
}

Complaints

Complaint list stores email addresses of recipients who marked your messages as a spam (for ESPs that support FBL).

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

View all complaints

GET /<domain>/complaints

Paginate over a list of complaints for a domain.

Note

Via this API method complaints are returned in the alphabetical order. If you wish to poll for the recently occurred complaints, please consider using the Events API.

Parameter Description
limit Maximum number of records to return (optional, default: 100, max: 10000)

Example:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getComplaints() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/complaints")
            .basicAuth("api", API_KEY)
            .queryString("limit", "100")
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->get("$domain/complaints", array(
    'limit' => 10,
    'skip'  => 5
));
def get_complaints():
    return requests.get(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints",
        auth=("api", "YOUR_API_KEY"))
def get_complaints
  RestClient.get "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetComplaintsChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetComplaints ().Content.ToString ());
    }

    public static IRestResponse GetComplaints ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "{domain}/complaints";
        return client.Execute (request);
    }

}
func GetComplaints(domain, apiKey string) (int, []mailgun.Complaint, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetComplaints()
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/${DOMAIN}/complaints`, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "items":
    [
      {
        "address": "alice@example.com",
        "created_at": "Fri, 21 Oct 2011 11:02:55 GMT"
      },
      ...
    ],
  "paging":
    {
      "first": <first page URL>,
      "next": <next page URL>,
      "previous": <previous page URL>,
      "last": <last page URL>
    }
}

View a single complaint

GET /<domain>/complaints/<address>

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

Example:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints/baz@example.com
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getComplaint() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/complaints/baz@example.com")
            .basicAuth("api", API_KEY)
            .asJson();

           return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';
$complaint = 'user@example.com';

# Issue the call to the client.
$result = $mgClient->get("$domain/complaints/$complaint");
def get_complaint():
    return requests.get(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints/baz@example.com",
        auth=("api", "YOUR_API_KEY"))
def get_complaint
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints/"\
                 "baz@example.com"){|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetComplaintChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetComplaint ().Content.ToString ());
    }

    public static IRestResponse GetComplaint ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "{domain}/complaints/baz@example.com";
        return client.Execute (request);
    }

}
func GetComplaints(domain, apiKey string) (mailgun.Complaint, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetSingleComplaint("baz@example.com")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/${DOMAIN}/complaints/baz@example.com`, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "address": "baz@example.com",
  "created_at": "Fri, 21 Oct 2011 11:02:55 GMT"
}
404
{
  "message": "No spam complaints found for this address"
}

Add a single complaint

POST /<domain>/complaints

Add an address to the complaints list.

Parameter Description
address Valid email address
created_at Timestamp of a complaint event in RFC2822 format (optional, default: current time)

Example:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints \
    -F address='bob@example.com'
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

     // ...

    public static JsonNode addComplaint() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/complaints")
                       .basicAuth("api", API_KEY)
                       .field("address", "bob@example.com")
                       .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->post("$domain/complaints", array('address' => 'bob@example.com'));
def add_complaint():
    return requests.post(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints",
        auth=("api", "YOUR_API_KEY"),
        data={'address': 'bob@example.com'})
def add_complaint
  RestClient.post "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/complaints",
  :address => 'bob@example.com'
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddComplaintChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (AddComplaint ().Content.ToString ());
    }

    public static IRestResponse AddComplaint ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "{domain}/complaints";
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.AddParameter ("address", "bob@example.com");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func CreateComplaint(domain, apiKey, emailAddress string) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.CreateComplaint("bob@example.com")
}

.. code-block:: node

var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.post(`/${DOMAIN}/complaints`, {"address" : "bob@example.com"}, function (error, body) {
  console.log(body);
});

Expected response:

200
{
  "message": "Address has been addded to the complaints table",
  "address": "bob@example.com"
}

Add multiple complaints

POST /<domain>/complaints, Content-Type: application/json

Add multiple complaint records to the complaint list in a single API call.

Request body is expected to be a valid JSON encoded string containing up to 1000 complaint records in the following format.

[
  {
    "address": "alice@example.com",
    "created_at": "Thu, 13 Oct 2011 18:02:00 UTC"
  },
  {
    "address": "bob@example.com"
  }
]

Fields within each individual complaint record are the same as for the “add a single unsubscribe” API method, with the same defaults and optionality rules.

Note

The current versions of our language libraries do not support adding multiple complaints yet.

Expected response:

200
{
  "message": "2 complaint addresses have been added to the complaints table"
}

Delete a single complaint

DELETE /<domain>/complaints/<address>

Remove a given spam complaint.

Expected response:

200
{
  "message": "Spam complaint has been removed"
}