Inbox Placement v2

A seed list is an object that provides the mailing list for your inbox placement test. It also acts as a container for all the results of those tests and will aggregate the stats of all the tests.

When you create a seed list you will be provided a mailing list. You may adjust this mailing list as you see fit, but you must send to the target_email otherwise a placement test will not be run.

Generate a seed list

POST /v4/inbox/seedlists

Generate a seed list. The available form fields are as follows:

Field Description
sending_domains The sending domains that messages will come from. You may specify this multiple times. At least one is required.
name The name that you would like to use for this seed list.
seed_filter A regular expression that will be applied to addresses in the mailing list.
curl -X POST https://api.mailgun.net/v4/inbox/seedlists \
  -F 'sending_domains=domain.com' \
  --user 'api:<YOUR_API_KEY>'
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 createSeedList() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v4/inbox/seedlists")
            .basicAuth("api", API_KEY)
            .field("sending_domains", "domain.com")
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function create_seed_list() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'sending_domains'=> 'domain.com',
      )
  );

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def create_seed_list():
    data = {'sending_domains': 'domain.com'}
    return requests.post(
        "https://api.mailgun.net/v4/inbox/seedlists", data=data
        auth=('api', 'YOUR_API_KEY'))
def create_seed_list
  data = {'sending_domains'=> 'domain.com' }
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v4/inbox/seedlists",
                  fields_hash.merge(data))
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class CreateInboxPlacementTest
{

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

    public static IRestResponse CreateSeedList ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/seedlists");
        client.Authenticator =
            new HttpBasicAuthenticator ("api", "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("sending_domains", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "inbox/seedlists";
        request.Method = Method.POST;
        return client.Execute (request);
    }
}

Example reponse for creating a seed list.

{
  "kid": "610abd2009b08f382ac86c45",
  "created_at": "2021-08-04T16:15:28.08Z",
  "updated_at": "2021-08-04T16:15:28.08Z",
  "last_result_at": "0001-01-01T00:00:00Z",
  "target_email": "ibp-12345678-1234-1234-1234-123456789012@domain.com",
  "sending_domains": [
    "yourdomain.com"
  ],
  "has_results": false,
  "name": "My campaign inbox test",
  "seed_filter": ".*",
  "mailing_list": "ibp-12345678-1234-1234-1234-123456789012@domain.com,another@email.com",
  "delivery_stats": {
    "all": {
      "delivered": 0,
      "missing": 0,
      "pending": 0,
      "spam": 0,
      "inbox": 0,
      "total": 0,
      "provider": "all"
    }
  },
  "results": []
}

Field Explanation:

Name Type Description
kid string Unique identifier for a seed list.
created_at datetime Date and time that seed list was created.
updated_at datetime Date and time that seed list was updated. Will update whenever it is changed.
last_result_at datetime Date and time that seed list was updated. Will update whenever a new result comes in.
target_email string The required email address that must be included in a mailing list for an inbox placement test to work.
sending_domains array The list of possible domains that the messages must come from.
has_results bool A flag that is true when results exist for this seed list
name string The name of the seed list
seed_filter string A regular expression value that will be used to filter the list of seeds in the seed list.
mailing_list string A mailing list that contains the target email, and available seeds.
delivery_stats object An object that contains sub-objects that describe delivery stats. See below.
results array An array of results from the seed list’s tests.

Delivery Stats

Delivery stats is an object that is included with seed list and results from the API. It is an attribute of the main object that is returned. A sample object:

 "delivery_stats": {
  "all": {
    "delivered": 10,
    "missing": 1,
    "pending": 0,
    "spam": 3,
    "inbox": 6,
    "total": 10,
    "provider": "all"
  },
  "yahoo.com": {
    "delivered": 4,
    "missing": 1,
    "pending": 0,
    "spam": 0,
    "inbox": 4,
    "total": 5,
    "provider": "yahoo.com"
  },
  "gmail.com": {
    "delivered": 5,
    "missing": 0,
    "pending": 0,
    "spam": 3,
    "inbox": 2,
    "total": 5,
    "provider": "gmail.com"
  }
}

Field Explanation:

Name Type Description
sub-object -“subkey” object The sub-object of the main delivery_stats object is divided by provider. There will always be an “all” provider that is the total sum.
delivered number The amount of messages that were received by the system.
missing number The amount of messages that were not received by the required reporting time period.
pending number The amount of messages that have yet to be received within the required reporting time period.
spam number The amount of messages that were detected in the provider’s spam folder.
inbox number The amount of messages that were detected in a non-spam folder.
total number The amount of messages that are expected.
provider string The provider that these mailboxes are a part of (identical to key).

Results

A result is an object summarizing Inbox Placement tests sent to the target_email.

{
  "result_id": "12345678-1234-1234-1234-123456789012",
  "subject": "IBP Test - 1",
  "sender": "generated@yourdomain.com",
  "delivery_stats": {
    "all": {
      "delivered": 7,
      "missing": 0,
      "pending": 0,
      "spam": 2,
      "inbox": 5,
      "total": 7,
      "provider": "all",
      "categories": {}
    }
  }
}

Field Explanation:

Name Type Description
result_id string Unique idetifier for a received test.
subject string The subject of the email sent to the target_email.
sender string Sender address of the email sent to the target_email.
delivery_stats object An object that contains sub-objects that describe delivery stats. See above.

Get all seed lists

GET /v4/inbox/seedlists

Get a list of all of your seed lists. You can filter this using the available filters. These can be listed from the “Get all available filters for seed lists” endpoint described below.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/seedlists
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 getSeedLists() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/seedlists")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the Inbox Placement endpoint.
# Consider using the following php curl function.
function get_seed_lists() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_seed_lists():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/seedlists",
        auth=('api', 'YOUR_API_KEY'))
def get_seed_lists
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/seedlists"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTests
{

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

    public static IRestResponse GetSeedLists ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/inbox/seedlists";
        return client.Execute (request);
    }

}

Example response for listing seed lists.

{
  "items": [
    {
      "kid": "123456789123456789123456",
      "created_at": "2021-08-02T23:10:17.915Z",
      "updated_at": "2021-08-03T17:26:55.629Z",
      "last_result_at": "2021-08-03T17:26:55.629Z",
      "target_email": "ibp-12345678-1234-1234-1234-123456789012@domain.com",
      "sending_domains": [
        "mydomain.com"
      ],
      "has_results": true,
      "name": "Inbox Placement Test",
      "seed_filter": ".*",
      "mailing_list": "ibp-12345678-1234-1234-1234-123456789012@domain.com,some@where.com",
      "delivery_stats": {
        "all": {
          "delivered": 7,
          "missing": 0,
          "pending": 0,
          "spam": 2,
          "inbox": 5,
          "total": 7,
          "provider": "all"
        }
      },
      "results": [
        {
          "result_id": "12345678-1234-1234-1234-123456789012",
          "subject": "IBP Test - 1",
          "sender": "generated@yourdomain.com",
          "delivery_stats": {
            "all": {
              "delivered": 7,
              "missing": 0,
              "pending": 0,
              "spam": 2,
              "inbox": 5,
              "total": 7,
              "provider": "all",
              "categories": {}
            }
          }
        }
      ]
    }
  ],
  "paging": {
    "first": "http://domain.com/v4/inbox/seedlists?ascending=0&limit=1",
    "last": "http://domain.com/v4/inbox/seedlists?ascending=1&limit=1",
    "next": "http://domain.com/v4/inbox/seedlists?ascending=0&cursor=123987123981723987873497&limit=1",
    "previous": "http://domain.com/v4/inbox/seedlists?ascending=1&cursor=123987123981723987873487&limit=1"
  },
  "total": 32
}

Field Explanation:

Name Type Description
items array A list of seed list objects (same fields as above).
paging object A paging sub-object to navigate through sections of data.
total number The total amount of seed lists.

Paging sub-object

The paging sub-object assists with navigating paginated responses. For a variety of reasons the number of items that can be returned in a response has been limited. This object contains the following fields:

Name Type Description
first url A url address to the first item of this set
last url A url address to the last item of this set
next url A url address to the next item of this set
previous url A url address to the previous item of this set

Additionally you can interact with the pagination through a few fields added to the query-string of your request:

Name Type Description
limit number A limit on the number of items that can be returned (defaults to 25)
offset number A the amount of items to “move” by
ascending bool A flag that will set the order of the pagination
cursor string A unique id that can be used as a “pivot” of where you are in the set
sort string The parameter to sort by (EXPERIMENTAL)

Note: cursor and offset may not both be used at the same time

Get a seed list

You can select a single seed list with this endpoint.

GET /v4/inbox/seedlists/ibp-seedlist-address@domain.net
curl -X POST https://api.mailgun.net/v3/inbox/tests \
  -F 'domain=domain.com' \
  -F 'subject=testSubject' \
  -F 'from=user@sending_domain.com' \
  --form-string html='<html>HTML version of the body</html>' \
  --user 'api:<YOUR_API_KEY'>'
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 validateMailingList() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/inbox/tests")
            .basicAuth("api", API_KEY)
            .field("domain", "domain.com")
            .field("subject", "testSubject")
            .field("from", "user@sending_domain.com")
            .field("html", "<html>HTML version of the body</html>")
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function create_inbox_placement_test() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'domain'=> 'domain.com',
      'from'=> 'user@sending_domain.com',
      'subject'=>'testSubject',
      'html'=>'<html>HTML version of the body</html>',
      )
  );

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def create_inbox_placement_test():
    data = {'domain': 'domain.com',
            'from': 'user@sending_domain.com',
            'subject': 'testSubject',
            'html': '<html>HTML version of the body</html>' }
    return requests.post(
        "https://api.mailgun.net/v3/inbox/tests", data=data
        auth=('api', 'YOUR_API_KEY'))
def validate_mailing_list
  data = {'domain'=> 'domain.com',
          'from'=> 'user@sending_domain.com',
          'subject'=> 'testSubject',
          'html'=> '<html>HTML version of the body</html>' }
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v3/inbox/tests",
                  fields_hash.merge(data))
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class CreateInboxPlacementTest
{

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

    public static IRestResponse StartInboxPlacementTest ()
    {
        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 = "inbox/tests";
        request.AddParameter ("from", "user@sending_domain.com'");
        request.AddParameter ("domain", "domain.com");
        request.AddParameter ("subject", "testSubject");
        request.AddParameter ("html", "<html>HTML version of the body</html>");
        request.Method = Method.POST;
        return client.Execute (request);
    }
}

Example response of getting a single seed list.

{
  "kid": "610abd2009b08f382ac86c45",
  "created_at": "2021-08-04T16:15:28.08Z",
  "updated_at": "2021-08-04T16:15:28.08Z",
  "last_result_at": "0001-01-01T00:00:00Z",
  "target_email": "ibp-seedlist-address@domain.net",
  "sending_domains": [
    "yourdomain.com"
  ],
  "has_results": false,
  "name": "My campaign inbox test",
  "seed_filter": ".*",
  "mailing_list": "ibp-seedlist-address@domain.net,another@email.com",
  "delivery_stats": {
    "all": {
      "delivered": 0,
      "missing": 0,
      "pending": 0,
      "spam": 0,
      "inbox": 0,
      "total": 0,
      "provider": "all"
    }
  },
  "results": [
    {
      "result_id": "12345678-1234-1234-1234-123456789012",
      "subject": "IBP Test - 1",
      "sender": "generated@yourdomain.com",
      "delivery_stats": {
        "all": {
          "delivered": 7,
          "missing": 0,
          "pending": 0,
          "spam": 2,
          "inbox": 5,
          "total": 7,
          "provider": "all",
          "categories": {}
        }
      }
    }
  ]
}
Name Type Description
kid string Unique identifier for a seed list.
created_at datetime Date and time that seed list was created.
updated_at datetime Date and time that seed list was updated. Will update whenever it is changed.
last_result_at datetime Date and time that seed list was updated. Will update whenever a new result comes in.
target_email string The required email address that must be included in a mailing list for an inbox placement test to work.
sending_domains array The list of possible domains that the messages must come from.
has_results bool A flag that is true when results exist for this seed list
name string The name of the seed list
seed_filter string A regular expression value that will be used to filter the list of seeds in the seed list.
mailing_list string A mailing list that contains the target email, and available seeds.
delivery_stats object An object that contains sub-objects that describe delivery stats. See below.
results array An array of results from the seed list’s tests.

Get all iterable attributes of seed lists

You can use this endpoint to find all attributes that are available for listing values of.

GET /v4/inbox/seedlists/a
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/inbox/seedlists/a
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 getSeedListAttributes() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/seedlists/a")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_seed_list_attributes() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists/a');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_seed_list_attributes():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/seedlists/a",
        auth=('api', 'YOUR_API_KEY'))
def get_seed_list_attributes
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/seedlists/a"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetSeedListAttributes()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest();
        request.Resource = "/inbox/seedlists/a";
        return client.Execute(request);
    }

}

Example response of seed list attributes.

{
 "items": {
   "attribute": "available attributes",
   "values": [
     "name"
   ]
 }
}
Name Type Description
attribute string A string describing what was selected.
values array A list of attributes that can be retrieved from the API.

Get all values of a specific attribute of your seed lists

You can use this endpoint to find all the values for a particular attribute. This can be used to produce autocomplete or suggestions from a frontend.

GET /v4/inbox/seedlists/a/attribute
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/inbox/seedlists/a/ATTRIBUTE
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 getSeedListAttribute() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/seedlists/a/ATTRIBUTE")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_seed_list_attribute() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists/a/ATTRIBUTE');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_seed_list_attribute():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/seedlists/a/ATTRIBUTE",
        auth=('api', 'YOUR_API_KEY'))
def get_seed_list_attribute
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/seedlists/a/ATTRIBUTE"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetSeedListAttribute()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest();
        request.AddParameter ("attribute", "ATTRIBUTE", ParameterType.UrlSegment);
        request.Resource = "/inbox/seedlists/a/{attribute}";
        return client.Execute(request);
    }

}

Example response of seed list attribute values.

{
 "items": {
   "attribute": "name",
   "values": [
     "Inbox Placement Test",
     "My email campaign"
   ]
 }
}
Name Type Description
attribute string A string describing what was selected.
values array A list of attributes that can be retrieved from the API.

Get all available filters for seed lists

You can use this endpoint to list the available filters for seed lists.

GET /v4/inbox/seedlists/_filters
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/inbox/seedlists/_filters
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 getSeedListFilters() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/seedlists/_filters")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_seed_list_filters() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists/_filters');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_seed_list_filters():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/seedlists/_filters",
        auth=('api', 'YOUR_API_KEY'))
def get_seed_list_filters
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/seedlists/_filters"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetSeedListFilters()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest();
        request.Resource = "/inbox/seedlists/_filters";
        return client.Execute(request);
    }

}

Example response of seed list filters.

{
 "supported_filters": {
   "filters": [
     {
       "parameter": "name",
       "description": "Get seedlists by name"
     },
     {
       "parameter": "time_before",
       "description": "Get seedlists before date"
     },
     {
       "parameter": "time_after",
       "description": "Get seedlists after date"
     }
   ]
 }
}
Name Type Description
parameter string The key of the parameter you can pass in your query string.
description string A description of the filter

Delete a seed list

You can delete a seed list with this endpoint. The results under it will not be kept.

DELETE /v4/inbox/seedlists/ibp-seedlist-address@domain.net
curl -s --user 'api:YOUR_API_KEY' -X DELETE -G \
    https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL
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 deleteInboxPlacementTest() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.delete("https://api.mailgun.net/v4/inbox/seedlists/{TARGET_EMAIL}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function delete_inbox_placement_test() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def delete_inbox_placement_test():
    return requests.delete(
        "https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL",
        auth=('api', 'YOUR_API_KEY'))
def delete_inbox_placement_test
  RestClient.delete("https://api:YOUR_API_KEY"\
                    "@api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL"\
                    {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse DeleteInboxPlacementTest()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest(Method.DELETE);
        request.AddParameter ("target_email", "TARGET_EMAIL", ParameterType.UrlSegment);
        request.Resource = "/inbox/seedlists/{target_email}";
        return client.Execute(request);
    }

}

This does not return any value.

Update a seed list

You can update a seed list with this endpoint. Modifying the sending domains or the seed filter will not affect historical results.

PUT /v4/inbox/seedlists/ibp-seedlist-address@domain.net

Update a seed list. The available form fields are as follows:

Field Description
sending_domains Update the sending domains of the seed list. You can specify this multiple times.
name Update the name of the seed list.
seed_filter Update the regular expression that will be applied to addresses in the mailing list.
curl -X PUT https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL \
  -F 'sending_domains=domain.com' \
  --user 'api:<YOUR_API_KEY>'
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 createSeedList() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.put("https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL")
            .basicAuth("api", API_KEY)
            .field("sending_domains", "domain.com")
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function create_seed_list() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'sending_domains'=> 'domain.com',
      )
  );

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def create_seed_list():
    data = {'sending_domains': 'domain.com'}
    return requests.put(
        "https://api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL", data=data
        auth=('api', 'YOUR_API_KEY'))
def create_seed_list
  data = {'sending_domains'=> 'domain.com' }
  RestClient.put("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v4/inbox/seedlists/TARGET_EMAIL",
                  fields_hash.merge(data))
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class CreateInboxPlacementTest
{

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

    public static IRestResponse CreateSeedList ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api", "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("sending_domains", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "inbox/seedlists/TARGET_EMAIL";
        request.Method = Method.PUT;
        return client.Execute (request);
    }
}
{
  "kid": "610abd2009b08f382ac86c45",
  "created_at": "2021-08-04T16:15:28.08Z",
  "updated_at": "2021-08-04T16:15:28.08Z",
  "last_result_at": "0001-01-01T00:00:00Z",
  "target_email": "ibp-seedlist-address@domain.net",
  "sending_domains": [
    "yourdomain.com"
  ],
  "has_results": false,
  "name": "My campaign inbox test",
  "seed_filter": ".*",
  "mailing_list": "ibp-seedlist-address@domain.net,another@email.com",
  "delivery_stats": {
    "all": {
      "delivered": 0,
      "missing": 0,
      "pending": 0,
      "spam": 0,
      "inbox": 0,
      "total": 0,
      "provider": "all"
    }
  },
  "results": []
}
Name Type Description
kid string Unique identifier for a seed list.
created_at datetime Date and time that seed list was created.
updated_at datetime Date and time that seed list was updated. Will update whenever it is changed.
last_result_at datetime Date and time that seed list was updated. Will update whenever a new result comes in.
target_email string The required email address that must be included in a mailing list for an inbox placement test to work.
sending_domains array The list of possible domains that the messages must come from.
has_results bool A flag that is true when results exist for this seed list
name string The name of the seed list
seed_filter string A regular expression value that will be used to filter the list of seeds in the seed list.
mailing_list string A mailing list that contains the target email, and available seeds.
delivery_stats object An object that contains sub-objects that describe delivery stats. See below.
results array An array of results from the seed list’s tests.

List Results

Test results are generated when a message has been received at the target_email. If a message is not received at the target email no seed test will be run. Results will contain the status of the monitored mail boxes and will provide stats of the test.

GET /v4/inbox/results

List all results for your account.

Field Description
rid Update the sending domains of the seed list. You can specify this multiple times.
name Update the name of the seed list.
seed_filter Update the regular expression that will be applied to addresses in the mailing list.
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/inbox/results
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 getResults() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/results")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the Inbox Placement endpoint.
# Consider using the following php curl function.
function get_results() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/results');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_results():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/results",
        auth=('api', 'YOUR_API_KEY'))
def get_results
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/results"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTests
{

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

    public static IRestResponse GetResults ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/inbox/results";
        return client.Execute (request);
    }

}
{
 "items": [
   {
     "rid": "123456789012345678901234",
     "result_id": "12345678-1234-1234-1234-123456789012",
     "keybox_email": "ibp-00410325-1c95-492e-bc35-c19899802494@mailgun.net",
     "subject": "A subject of things",
     "sender": "person@domain.com",
     "name": "Such list",
     "created_at": "2021-08-03T14:20:40.301Z",
     "updated_at": "2021-08-03T14:36:53.841Z",
     "seed_results": [
       {
         "email": "mail@box.com",
         "provider": "box.com",
         "destination": "inbox",
         "state": "delivered",
         "originating_ip": "123.123.123.123",
         "tags": [
           "inbox"
         ]
       }
     ]
   }
 ]
 }
Name Type Description
rid string Unique identifier for a results.
keybox_email string The target email of the seed list associated with this result.
subject string The subject of the email received by the seed list mailbox (target_email)
sender string The email address of the sender received by the seed list mailbox (target_email). All other results must come from the same sender.
name string The name of the seed list.
created_at datetime Date and time that the results were created.
updated_at datetime Date and time that the results were updated. Will update whenever a mailbox within the test receives mail.
seed_results object A sub-object that contains the status of each individual seed mailbox.
status string Will show “processing” or “complete”.
delivery_stats object A sub-object that provides the stats of this result.

Seed Results

The seed results sub-object will provide the details of the individual seed mail boxes.

Field Explanation:

Name Type Description
email string The email address of the mailbox.
provider string The email provider of the mailbox (usually the domain).
destination string Either “inbox” or “spam”
state string Whether or not the mailbox has received a message
originating_ip string The IP address from which the message came from (if available)
tags array The folder, or labels of where the message ended up.

Get Available Result Filters

GET /v4/inbox/results/_filters
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/results/_filters
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 getResultsFilters() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/results/_filters")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the Inbox Placement endpoint.
# Consider using the following php curl function.
function get_results_filters() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/results/_filters');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_results_filters():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/results/_filters",
        auth=('api', 'YOUR_API_KEY'))
def get_results_filters
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/results/_filters"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTests
{

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

    public static IRestResponse GetResultsFilters ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/inbox/results/_filters";
        return client.Execute (request);
    }

}

Example response of getting the available results filters.

Get all iterable attributes of results

GET /v4/inbox/results/a

Example response of getting the result attributes.

Get all values of a specific attribute of your results lists

GET /v4/inbox/results/a/attribute
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/inbox/results/a/ATTRIBUTE
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 getResultsAttribute() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/results/a/ATTRIBUTE")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_results_attribute() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/results/a/ATTRIBUTE');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_results_attribute():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/results/a/ATTRIBUTE",
        auth=('api', 'YOUR_API_KEY'))
def get_results_attribute
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/results/a/ATTRIBUTE"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetResultsAttribute()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest();
        request.AddParameter ("attribute", "ATTRIBUTE", ParameterType.UrlSegment);
        request.Resource = "/inbox/results/a/{attribute}";
        return client.Execute(request);
    }

}

You can use this endpoint to find all the values for a particular attribute. This can be used to produce autocomplete or suggestions from a frontend.

Example response of response attribute values.

{
  "items": {
    "attribute": "subject",
    "values": [
      "This is a subject",
      "We've been trying to contact you",
      "about your car's extended warranty"
    ]
  }
}

Get a specific result

GET /v4/inbox/results/UUID
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/inbox/results/UUID
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 getResults() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/inbox/results/{UUID}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_results() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/results/UUID');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_results():
    return requests.get(
        "https://api.mailgun.net/v4/inbox/results/UUID",
        auth=('api', 'YOUR_API_KEY'))
def get_results
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/inbox/results/UUID"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetResult()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest();
        request.AddParameter ("uuid", "UUID", ParameterType.UrlSegment);
        request.Resource = "/inbox/results/{uuid}";
        return client.Execute(request);
    }

}

You can use this endpoint to get a single result.

Name Type Description
rid string Unique identifier for a results.
keybox_email string The target email of the seed list associated with this result.
subject string The subject of the email received by the seed list mailbox (target_email)
sender string The email address of the sender received by the seed list mailbox (target_email). All other results must come from the same sender.
name string The name of the seed list.
created_at datetime Date and time that the results were created.
updated_at datetime Date and time that the results were updated. Will update whenever a mailbox within the test receives mail.
seed_results object A sub-object that contains the status of each individual seed mailbox.
status string Will show “processing” or “complete”.
delivery_stats object A sub-object that provides the stats of this result.
{
 "result": {
   "rid": "123456789012345678901234",
   "result_id": "12345678-1234-1234-1234-123456789012",
   "keybox_email": "ibp-00410325-1c95-492e-bc35-c19899802494@mailgun.net",
   "subject": "A subject of things",
   "sender": "person@domain.com",
   "name": "Such list",
   "created_at": "2021-08-03T14:20:40.301Z",
   "updated_at": "2021-08-03T14:36:53.841Z",
   "seed_results": [
     {
       "email": "mail@box.com",
       "provider": "box.com",
       "destination": "inbox",
       "state": "delivered",
       "originating_ip": "123.123.123.123",
       "tags": [
         "inbox"
       ]
     }
   ]
 }
}

Delete results

Use this endpoint to delete a result.

DELETE /v4/inbox/results/UUID
curl -s --user 'api:YOUR_API_KEY' -X DELETE -G \
    https://api.mailgun.net/v4/inbox/results/UUID
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 deleteResults() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.delete("https://api.mailgun.net/v4/inbox/results/{UUID}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function delete_results() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/inbox/results/UUID');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def delete_results():
    return requests.delete(
        "https://api.mailgun.net/v4/inbox/results/UUID",
        auth=('api', 'YOUR_API_KEY'))
def delete_results
  RestClient.delete("https://api:YOUR_API_KEY"\
                    "@api.mailgun.net/v4/inbox/results/UUID"\
                    {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class Results
{

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

    public static IRestResponse DeleteResults()
    {
        RestClient client = new RestClient();
        client.BaseUrl = new Uri("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest(Method.DELETE);
        request.AddParameter ("uuid", "UUID", ParameterType.UrlSegment);
        request.Resource = "/inbox/results/{uuid}";
        return client.Execute(request);
    }

}

This does not return any value.

Inbox Placement v1 Deprecated

Start an inbox placement test

POST /v3/inbox/tests

Start an inbox placement test. The required form fields are as follows.

Field Description
domain The sending domain registered with mailgun to send the messages with.
subject The subject associated with the message being tested.
html The html that makes up the body of the message being tested.
from The sending address associated with the sending of the message.
curl -X POST https://api.mailgun.net/v3/inbox/tests \
  -F 'domain=domain.com' \
  -F 'subject=testSubject' \
  -F 'from=user@sending_domain.com' \
  --form-string html='<html>HTML version of the body</html>' \
  --user 'api:<YOUR_API_KEY'>'
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 validateMailingList() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/inbox/tests")
            .basicAuth("api", API_KEY)
            .field("domain", "domain.com")
            .field("subject", "testSubject")
            .field("from", "user@sending_domain.com")
            .field("html", "<html>HTML version of the body</html>")
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function create_inbox_placement_test() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'domain'=> 'domain.com',
      'from'=> 'user@sending_domain.com',
      'subject'=>'testSubject',
      'html'=>'<html>HTML version of the body</html>',
      )
  );

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def create_inbox_placement_test():
    data = {'domain': 'domain.com',
            'from': 'user@sending_domain.com',
            'subject': 'testSubject',
            'html': '<html>HTML version of the body</html>' }
    return requests.post(
        "https://api.mailgun.net/v3/inbox/tests", data=data
        auth=('api', 'YOUR_API_KEY'))
def validate_mailing_list
  data = {'domain'=> 'domain.com',
          'from'=> 'user@sending_domain.com',
          'subject'=> 'testSubject',
          'html'=> '<html>HTML version of the body</html>' }
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v3/inbox/tests",
                  fields_hash.merge(data))
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class CreateInboxPlacementTest
{

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

    public static IRestResponse StartInboxPlacementTest ()
    {
        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 = "inbox/tests";
        request.AddParameter ("from", "user@sending_domain.com'");
        request.AddParameter ("domain", "domain.com");
        request.AddParameter ("subject", "testSubject");
        request.AddParameter ("html", "<html>HTML version of the body</html>");
        request.Method = Method.POST;
        return client.Execute (request);
    }
}

Example response for creating an inbox placement test.

{
    "tid": "5e22167af8424f444ca6d8e2"
}

Field Explanation:

Name Type Description
tid string Unique identifier for an inbox placement test.

Get all inbox placement tests

This API endpoint is used for interfacing with the inbox placement service. Pricing details for Mailgun’s inbox placement service can be found on our pricing page. Mailgun’s inbox placement service is intended to be used for seed testing for emails. Refer to our Acceptable Use Policy (AUP) for more information about how to use the service appropriately.

GET /v3/inbox/tests

Retrieve a list of all the inbox placement tests and their results ran on the account.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/inbox/tests
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 getInboxPlacementTests() throws UnirestException {

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

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the Inbox Placement endpoint.
# Consider using the following php curl function.
function get_inbox_placement_tests() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_inbox_placement_tests():
    return requests.get(
        "https://api.mailgun.net/v3/inbox/tests",
        auth=('api', 'YOUR_API_KEY'))
def get_inbox_placement_tests
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/inbox/tests"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTests
{

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

    public static IRestResponse GetInboxPlacementTests ()
    {
        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 = "/inbox/tests";
        return client.Execute (request);
    }

}

Example response of getting a list of inbox placement tests.

{
  "paging": {
    "first": "https://api.mailgun.net/v3/inbox/tests?ascending=0",
    "last": "https://api.mailgun.net/v3/inbox/tests?ascending=1",
    "next": "https://api.mailgun.net/v3/inbox/tests?ascending=0&cursor=5e22167af8424f444ca6d8ea",
    "previous": "https://api.mailgun.net/v3/inbox/tests?ascending=1&cursor=5e22167af8424f444ca6d8e2"
  },
  "tests": [
    {
      "tid": "5e22167af8424f444ca6d8e2",
      "counts": {
        "inbox": 2,
        "junk": 1,
        "missing": 0
      },
      "domain": "ibp.voxcreator.com",
      "status": "completed",
      "seeds": [
        "joesmith915@o365.mailgun.email",
        "joesmith916@o365.mailgun.email",
        "janedoe@o365.mailgun.email"
      ],
      "start_time": "2020-01-17T20:18:02.093Z",
      "end_time": "2020-01-17T20:33:02.097Z",
      "summary": {
        "stats": {
          "averages": {
            "mailgun_send": {
              "inbox": 95.48,
              "junk": 3.2,
              "missing": 1.32
            }
          }
        }
      },
      "subject": "This Service is Awesome!"
    },
    {
      "tid": "5e22167af8424f444ca6d8ea",
      "counts": {
        "inbox": 2,
        "junk": 1,
        "missing": 0
      },
      "domain": "ibp.voxcreator.com",
      "status": "completed",
      "seeds": [
        "joesmith915@o365.mailgun.email",
        "joesmith916@o365.mailgun.email",
        "janedoe@o365.mailgun.email"
      ],
      "start_time": "2020-01-17T20:18:02.093Z",
      "end_time": "2020-01-17T20:33:02.097Z",
      "summary": {
        "stats": {
          "averages": {
            "mailgun_send": {
              "inbox": 95.48,
              "junk": 3.2,
              "missing": 1.32
            }
          }
        }
      },
      "subject": "This Mail is Awesome!"
    }
  ],
  "total": 2
}

Field Explanation:

Name Type Description
paging object Urls used to page through the list of inbox placement tests.
tests array List of inbox placement tests.
total integer Total number of inbox placement tests ran for the account

Retrieve individual test details

GET /v3/inbox/tests/<test_id>

Retrieve a single inbox placement test.

Parameter Description
test_id The unique identifier for the inbox placement test.
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/inbox/tests/TEST_ID
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 getInboxPlacementTest() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/inbox/tests/{test_id}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_inbox_placement_test() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests/TEST_ID');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_inbox_placement_test():
    return requests.get(
        "https://api.mailgun.net/v3/inbox/tests/TEST_ID",
        auth=('api', 'YOUR_API_KEY'))
def get_inbox_placement_test
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/inbox/tests/TEST_ID"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetInboxPlacementTest()
    {
        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 ("test_id", "TEST_ID", ParameterType.UrlSegment);
        request.Resource = "/inbox/tests/{test_id}";
        return client.Execute(request);
    }

}

Example response of getting an inbox placement test.

{
  "tid": "5e22167af8424f444ca6d8e2",
  "counts": {
    "inbox": 2,
    "junk": 1,
    "missing": 0
  },
  "domain": "inbox_placement.domain.com",
  "status": "completed",
  "seeds": [
    "joesmith915@o365.mailgun.email",
    "joesmith916@o365.mailgun.email",
    "janedoe@o365.mailgun.email"
  ],
  "start_time": "2020-01-17T20:18:02.093Z",
  "end_time": "2020-01-17T20:33:02.097Z",
  "summary": {
    "stats": {
      "averages": {
        "mailgun_send": {
          "inbox": 95.48,
          "junk": 3.2,
          "missing": 1.32
        }
      }
    }
  },
  "render_url": "https://mg-inbox-placement.s3.amazonaws.com/export/b156f44d9c27ee74422a3e38dd831343ec541938.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJR5LUWTPXYIVY4GA%2F20200118%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200118T225458Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=f255b140f0efa94507bb62542b7a1191faaac708588edcb0d5dfd88a777e0061",
  "subject": "This is an awesome API!"
}

Field Explanation:

Name Type Description
tid string Unique identifier for an inbox placement test.
counts object Total counts for the mailboxes where the messages landed across the seed address sent to.
domain string The sending domain used to send the messages to the seed addresses.
status string The current status for a test. e.g. (“running”, “completed”, “error”, “created”)
seeds array The seed addresses the test message was sent to.
start_time string The time in which the inbox placement test began.
end_time string The time in which the inbox placement test ended.
summary object A summarized view of the inbox placement test.
rendered_url string A link to a rendered version of the message that was sent to the seed addresses.
subject string The subject for the message that was sent to the seed addresses.

Delete an inbox placement test

DELETE /v3/inbox/tests/<test_id>

Delete a single inbox placement test.

Parameter Description
test_id The unique identifier for the inbox placement test.
curl -s --user 'api:YOUR_API_KEY' -X DELETE -G \
    https://api.mailgun.net/v3/inbox/tests/TEST_ID
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 deleteInboxPlacementTest() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.delete("https://api.mailgun.net/v3/inbox/tests/{test_id}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function delete_inbox_placement_test() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests/TEST_ID');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def delete_inbox_placement_test():
    return requests.delete(
        "https://api.mailgun.net/v3/inbox/tests/TEST_ID",
        auth=('api', 'YOUR_API_KEY'))
def delete_inbox_placement_test
  RestClient.delete("https://api:YOUR_API_KEY"\
                    "@api.mailgun.net/v3/inbox/tests/TEST_ID"\
                    {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse DeleteInboxPlacementTest()
    {
        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(Method.DELETE);
        request.AddParameter ("test_id", "TEST_ID", ParameterType.UrlSegment);
        request.Resource = "/inbox/tests/{test_id}";
        return client.Execute(request);
    }

}

Example response for deleting an inbox placement test.

{
    "message": "deleted"
}

Retrieve provider results (counters) for a test

GET /v3/inbox/tests/<test_id>/counters

Retrieve a provider breakdown of the inbox placement test’s counters.

Parameter Description
test_id The unique identifier for the inbox placement test.
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/inbox/tests/TEST_ID/counters
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 getInboxPlacementTestCounters() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/inbox/tests/{test_id}/counters")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_inbox_placement_test_counters() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests/TEST_ID/counters');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_inbox_placement_test_counters():
    return requests.get(
        "https://api.mailgun.net/v3/inbox/tests/TEST_ID/counters",
        auth=('api', 'YOUR_API_KEY'))
def get_inbox_placement_test_counters
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/inbox/tests/TEST_ID/counters"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetInboxPlacementTestCounters()
    {
        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 ("test_id", "TEST_ID", ParameterType.UrlSegment);
        request.Resource = "/inbox/tests/{test_id}/counters";
        return client.Execute(request);
    }
}

Example response for inbox placement counters.

{
  "counters": [
    {
      "inbox": 2,
      "junk": 1,
      "provider": "o365"
    },
  ]
}

Field Explanation:

Name Type Description
tid string Unique identifier for an inbox placement test.

Get all inbox placement test checks

GET /v3/inbox/tests/<test_id>/checks

Retrieve a list of all the checks sent for an inbox placement test.

Parameter Description
test_id The unique identifier for the inbox placement test.
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/inbox/tests/TEST_ID/checks
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 getInboxPlacementTestCounters() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/inbox/tests/{test_id}/checks")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_inbox_placement_test_checks() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests/TEST_ID/checks');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_inbox_placement_test_checks():
    return requests.get(
        "https://api.mailgun.net/v3/inbox/tests/TEST_ID/checks",
        auth=('api', 'YOUR_API_KEY'))
def get_inbox_placement_test_checks
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/inbox/tests/TEST_ID/checks"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetInboxPlacementTestChecks()
    {
        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 ("test_id", "TEST_ID", ParameterType.UrlSegment);
        request.Resource = "/inbox/tests/{test_id}/checks";
        return client.Execute(request);
    }
}

Example response of getting a list of all checks for an inbox placement test.

{
  "checks": [
    {
      "address": "aa_ext_test01mg@comcast.net",
      "provider": "comcast",
      "ip": "00.114.000.000",
      "folder": "inbox",
      "headers": "Return-Path: <bounce+b671ba.25af4b3-aa_ext_test01mg=comcast.net@test.domain.com>\r\nDelivered-To: aa_ext_test01mg@comcast.net\r\nReceived: from dovdir4-asa-04o.email.comcast.net ([96.114.154.247])\r\n\tby dovback4-asa-18o.email.comcast.net with LMTP\r\n\tid iD97DYUWIl58dAAAt8rViA\r\n\t(envelope-from <bounce+b671ba.25af4b3-aa_ext_test01mg=comcast.net@test.domain.com>)\r\n\tfor <aa_ext_test01mg@comcast.net>; Fri, 17 Jan 2020 20:18:13 +0000\r\nReceived: from dovpxy-asc-09o.email.comcast.net ([96.114.154.247])\r\n\tby dovdir4-asa-04o.email.comcast.net with LMTP\r\n\tid 2AU9DYUWIl79cAAAp4A1CQ\r\n\t(envelope-from <bounce+b671ba.25af4b3-aa_ext_test01mg=comcast.net@test.domain.com>)\r\n\tfor <aa_ext_test01mg@comcast.net>; Fri, 17 Jan 2020 20:18:13 +0000\r\nReceived: from resimta-po-40v.sys.comcast.net ([96.114.154.247])\r\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\r\n\tby dovpxy-asc-09o.email.comcast.net with LMTP id IC0YMYMWIl5eOQAAquDo3w\r\n\t; Fri, 17 Jan 2020 20:18:13 +0000\r\nReceived: from so254-22.mailgun.net ([00.114.000.000])\r\n\tby resimta-po-40v.sys.comcast.net with ESMTP\r\n\tid sY4Iie8ttwt3TsY4KiR4U0; Fri, 17 Jan 2020 20:18:12 +0000\r\nX-CAA-SPAM: F00000\r\nX-Xfinity-VAAS: gggruggvucftvghtrhhoucdtuddrgedugedrtdekgdegudcutefuodetggdotefrodftvfcurfhrohhfihhlvgemucevohhmtggrshhtqdftvghsihenuceurghilhhouhhtmecufedttdenucenucfjughrpeffshfkvffhufgtggeshhhqredttddtvdenucfhrhhomhepuhhsvghrsehisghprdhvohigtghrvggrthhorhdrtghomhenucffohhmrghinhepmhgrihhlghhunhdrtghomhdpthifihhtthgvrhdrtghomhenucfkphepudelkedriedurddvheegrddvvdenucfrrghrrghmpehhvghlohepshhovdehgedqvddvrdhmrghilhhguhhnrdhnvghtpdhinhgvthepudelkedriedurddvheegrddvvddpmhgrihhlfhhrohhmpegsohhunhgtvgdosgeijedusggrrddvhegrfhegsgefqdgrrggpvgigthgpthgvshhttddumhhgpegtohhmtggrshhtrdhnvghtsehisghprdhvohigtghrvggrthhorhdrtghomhdprhgtphhtthhopegrrggpvgigthgpthgvshhttddumhhgsegtohhmtggrshhtrdhnvghtnecuvehluhhsthgvrhfuihiivgeptd\r\nX-Xfinity-VMeta: sc=0.00;st=legit\r\nX-Xfinity-Message-Heuristics: IPv6:N;TLS=1;SPF=1;DMARC=\r\nAuthentication-Results: resimta-po-40v.sys.comcast.net;\r\n\tdkim=pass header.d=test.domain.com header.b=NA9s3uW5\r\nDKIM-Signature: a=rsa-sha256; v=1; c=relaxed/relaxed; d=test.domain.com; q=dns/txt;\r\n s=k1; t=1579292292; h=Mime-Version: Content-Type: Subject: From: To:\r\n Message-Id: Sender: Date: Content-Transfer-Encoding;\r\n bh=bYuUQQIdEIrM6gyAxa1Xp4Nd0A2cWpdksHogCDsE+j8=; b=NA9s3uW5ejKsh0a/lDlEEfoKhyh8OevkRYfDau6tqRIYw/82eEWHxSRQrbTdKjxOWSH4ZHwl\r\n DpigSIhjF3Ub5BQdV64LtN8Bcd1ps/2exdIa21qiKewJDFQht9KoLURTCI5FY+03dywAIeM4\r\n yOp9o/cuQTKJH2qM4iiDgRE0Gsg=\r\nX-Mailgun-Sending-Ip: 00.114.000.000\r\nX-Mailgun-Sid: WyJjYTRiMyIsICJhYV9leHRfdGVzdDAxbWdAY29tY2FzdC5uZXQiLCAiMjVhZjRiMyJd\r\nContent-Transfer-Encoding: quoted-printable\r\nReceived: by luna.mailgun.net with HTTP; Fri, 17 Jan 2020 20:18:11 +0000\r\nDate: Fri, 17 Jan 2020 20:18:11 +0000\r\nSender: user@test.domain.com\r\nMessage-Id: <20200117201811.1.BDA3E43254369346@test.domain.com>\r\nX-Mailgun-Seed-Test-Id: 5e22167af8424f444ca6d8e2\r\nTo: aa_ext_test01mg@comcast.net\r\nFrom: user@test.domain.com\r\nSubject: testSubject\r\nContent-Type: text/html; charset=\"ascii\"\r\nMime-Version: 1.0",
      "message_id": "<20200117201811.1.BDA3E43254369346@test.domain.com>",
      "time": "2020-01-17T20:18:08.8Z"
    },
    {
      "address": "aa_ext_test02mg@comcast.net",
      "provider": "comcast",
      "ip": "00.114.000.000",
      "folder": "inbox",
      "headers": "Return-Path: <bounce+1e9aa3.25af4b3-aa_ext_test02mg=comcast.net@test.domain.com>\r\nDelivered-To: aa_ext_test02mg@comcast.net\r\nReceived: from dovdir3-asa-01o.email.comcast.net ([96.114.154.247])\r\n\tby dovback3-asa-07o.email.comcast.net with LMTP\r\n\tid uCAWG4gWIl6IDgAAVWOgEw\r\n\t(envelope-from <bounce+1e9aa3.25af4b3-aa_ext_test02mg=comcast.net@test.domain.com>)\r\n\tfor <aa_ext_test02mg@comcast.net>; Fri, 17 Jan 2020 20:18:16 +0000\r\nReceived: from dovpxy-asc-01o.email.comcast.net ([96.114.154.247])\r\n\tby dovdir3-asa-01o.email.comcast.net with LMTP\r\n\tid 0CrqGogWIl7xTAAAwP0GGg\r\n\t(envelope-from <bounce+1e9aa3.25af4b3-aa_ext_test02mg=comcast.net@test.domain.com>)\r\n\tfor <aa_ext_test02mg@comcast.net>; Fri, 17 Jan 2020 20:18:16 +0000\r\nReceived: from resimta-po-40v.sys.comcast.net ([96.114.154.247])\r\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\r\n\tby dovpxy-asc-01o.email.comcast.net with LMTP id OD4qI4UWIl5UQQAAyeh4YQ\r\n\t; Fri, 17 Jan 2020 20:18:16 +0000\r\nReceived: from so254-22.mailgun.net ([00.114.000.000])\r\n\tby resimta-po-40v.sys.comcast.net with ESMTP\r\n\tid sY4Iie8ttwt3TsY4MiR4WV; Fri, 17 Jan 2020 20:18:16 +0000\r\nX-CAA-SPAM: F00000\r\nX-Xfinity-VAAS: gggruggvucftvghtrhhoucdtuddrgedugedrtdekgdegudcutefuodetggdotefrodftvfcurfhrohhfihhlvgemucevohhmtggrshhtqdftvghsihenuceurghilhhouhhtmecufedttdenucenucfjughrpeffshfkvffhufgtggeshhhqredttddtvdenucfhrhhomhepuhhsvghrsehisghprdhvohigtghrvggrthhorhdrtghomhenucffohhmrghinhepmhgrihhlghhunhdrtghomhdpthifihhtthgvrhdrtghomhenucfkphepudelkedriedurddvheegrddvvdenucfrrghrrghmpehhvghlohepshhovdehgedqvddvrdhmrghilhhguhhnrdhnvghtpdhinhgvthepudelkedriedurddvheegrddvvddpmhgrihhlfhhrohhmpegsohhunhgtvgdoudgvlegrrgefrddvhegrfhegsgefqdgrrggpvgigthgpthgvshhttddvmhhgpegtohhmtggrshhtrdhnvghtsehisghprdhvohigtghrvggrthhorhdrtghomhdprhgtphhtthhopegrrggpvgigthgpthgvshhttddvmhhgsegtohhmtggrshhtrdhnvghtnecuvehluhhsthgvrhfuihiivgeptd\r\nX-Xfinity-VMeta: sc=0.00;st=legit\r\nX-Xfinity-Message-Heuristics: IPv6:N;TLS=1;SPF=1;DMARC=\r\nAuthentication-Results: resimta-po-40v.sys.comcast.net;\r\n\tdkim=pass header.d=test.domain.com header.b=J/in82+r\r\nDKIM-Signature: a=rsa-sha256; v=1; c=relaxed/relaxed; d=test.domain.com; q=dns/txt;\r\n s=k1; t=1579292296; h=Mime-Version: Content-Type: Subject: From: To:\r\n Message-Id: Sender: Date: Content-Transfer-Encoding;\r\n bh=bYuUQQIdEIrM6gyAxa1Xp4Nd0A2cWpdksHogCDsE+j8=; b=J/in82+rjjHVoVLeZIlYl+9y7WFgUOcXlrt+P8gaGduSdCEc6MEWMmY8JHyI0X00OTOLRIqn\r\n 1me6suiWiv8F2ADgtK2H9PYwRNg5LomNBKn7j1UbdQP4C7oJ3eYtvA6DCA5KRkgsHOTHY+Kq\r\n /S49D6ajqrN4ZyB+XTLnA5IN8ew=\r\nX-Mailgun-Sending-Ip: 00.114.000.000\r\nX-Mailgun-Sid: WyJlOThhZiIsICJhYV9leHRfdGVzdDAybWdAY29tY2FzdC5uZXQiLCAiMjVhZjRiMyJd\r\nContent-Transfer-Encoding: quoted-printable\r\nReceived: by luna.mailgun.net with HTTP; Fri, 17 Jan 2020 20:18:09 +0000\r\nDate: Fri, 17 Jan 2020 20:18:09 +0000\r\nSender: user@test.domain.com\r\nMessage-Id: <20200117201809.1.82C23D86DE20410C@test.domain.com>\r\nX-Mailgun-Seed-Test-Id: 5e22167af8424f444ca6d8e2\r\nTo: aa_ext_test02mg@comcast.net\r\nFrom: user@test.domain.com\r\nSubject: testSubject\r\nContent-Type: text/html; charset=\"ascii\"\r\nMime-Version: 1.0",
      "message_id": "<20200117201809.1.82C23D86DE20410C@test.domain.com>",
      "time": "2020-01-17T20:18:08.8Z"
    }
  ]
}

Field Explanation:

Name Type Description
checks array Collection of checks that represent the messages sent to the seed mailboxes.

Get a single inbox placement test check

GET /v3/inbox/tests/<test_id>/checks/<address>

Retrieve a check sent for an inbox placement test.

Parameter Description
test_id The unique identifier for the inbox placement test.
address The seed address sent to in the inbox placement test.
curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/inbox/tests/TEST_ID/checks/ADDRESS
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 getInboxPlacementTestCheck() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/inbox/tests/{test_id}/checks/{address}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the inbox placement endpoint.
# Consider using the following php curl function.
function get_inbox_placement_test() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/inbox/tests/TEST_ID/checks/ADDRESS');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_inbox_placement_test_check():
    return requests.get(
        "https://api.mailgun.net/v3/inbox/tests/TEST_ID/checks/ADDRESS",
        auth=('api', 'YOUR_API_KEY'))
def get_inbox_placement_test_check
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/inbox/tests/TEST_ID/checks/ADDRESS"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class InboxPlacementTest
{

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

    public static IRestResponse GetInboxPlacementTestCheck()
    {
        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 ("test_id", "TEST_ID", ParameterType.UrlSegment);
        request.AddParameter ("address", "ADDRESS", ParameterType.UrlSegment);
        request.Resource = "/inbox/tests/{test_id}/checks/{address}";
        return client.Execute(request);
    }

}

Example response of getting a single check for an inbox placement test.

{
  "address": "aa_ext_test02mg@comcast.net",
  "provider": "comcast",
  "ip": "96.114.154.247",
  "folder": "inbox",
  "headers": "Return-Path: <bounce+1e9aa3.25af4b3-aa_ext_test02mg=comcast.net@test.domain.com>\r\nDelivered-To: aa_ext_test02mg@comcast.net\r\nReceived: from dovdir3-asa-01o.email.comcast.net ([96.114.154.247])\r\n\tby dovback3-asa-07o.email.comcast.net with LMTP\r\n\tid uCAWG4gWIl6IDgAAVWOgEw\r\n\t(envelope-from <bounce+1e9aa3.25af4b3-aa_ext_test02mg=comcast.net@test.domain.com>)\r\n\tfor <aa_ext_test02mg@comcast.net>; Fri, 17 Jan 2020 20:18:16 +0000\r\nReceived: from dovpxy-asc-01o.email.comcast.net ([96.114.154.247])\r\n\tby dovdir3-asa-01o.email.comcast.net with LMTP\r\n\tid 0CrqGogWIl7xTAAAwP0GGg\r\n\t(envelope-from <bounce+1e9aa3.25af4b3-aa_ext_test02mg=comcast.net@test.domain.com>)\r\n\tfor <aa_ext_test02mg@comcast.net>; Fri, 17 Jan 2020 20:18:16 +0000\r\nReceived: from resimta-po-40v.sys.comcast.net ([96.114.154.247])\r\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\r\n\tby dovpxy-asc-01o.email.comcast.net with LMTP id OD4qI4UWIl5UQQAAyeh4YQ\r\n\t; Fri, 17 Jan 2020 20:18:16 +0000\r\nReceived: from so254-22.mailgun.net ([198.61.254.22])\r\n\tby resimta-po-40v.sys.comcast.net with ESMTP\r\n\tid sY4Iie8ttwt3TsY4MiR4WV; Fri, 17 Jan 2020 20:18:16 +0000\r\nX-CAA-SPAM: F00000\r\nX-Xfinity-VAAS: gggruggvucftvghtrhhoucdtuddrgedugedrtdekgdegudcutefuodetggdotefrodftvfcurfhrohhfihhlvgemucevohhmtggrshhtqdftvghsihenuceurghilhhouhhtmecufedttdenucenucfjughrpeffshfkvffhufgtggeshhhqredttddtvdenucfhrhhomhepuhhsvghrsehisghprdhvohigtghrvggrthhorhdrtghomhenucffohhmrghinhepmhgrihhlghhunhdrtghomhdpthifihhtthgvrhdrtghomhenucfkphepudelkedriedurddvheegrddvvdenucfrrghrrghmpehhvghlohepshhovdehgedqvddvrdhmrghilhhguhhnrdhnvghtpdhinhgvthepudelkedriedurddvheegrddvvddpmhgrihhlfhhrohhmpegsohhunhgtvgdoudgvlegrrgefrddvhegrfhegsgefqdgrrggpvgigthgpthgvshhttddvmhhgpegtohhmtggrshhtrdhnvghtsehisghprdhvohigtghrvggrthhorhdrtghomhdprhgtphhtthhopegrrggpvgigthgpthgvshhttddvmhhgsegtohhmtggrshhtrdhnvghtnecuvehluhhsthgvrhfuihiivgeptd\r\nX-Xfinity-VMeta: sc=0.00;st=legit\r\nX-Xfinity-Message-Heuristics: IPv6:N;TLS=1;SPF=1;DMARC=\r\nAuthentication-Results: resimta-po-40v.sys.comcast.net;\r\n\tdkim=pass header.d=test.domain.com header.b=J/in82+r\r\nDKIM-Signature: a=rsa-sha256; v=1; c=relaxed/relaxed; d=test.domain.com; q=dns/txt;\r\n s=k1; t=1579292296; h=Mime-Version: Content-Type: Subject: From: To:\r\n Message-Id: Sender: Date: Content-Transfer-Encoding;\r\n bh=bYuUQQIdEIrM6gyAxa1Xp4Nd0A2cWpdksHogCDsE+j8=; b=J/in82+rjjHVoVLeZIlYl+9y7WFgUOcXlrt+P8gaGduSdCEc6MEWMmY8JHyI0X00OTOLRIqn\r\n 1me6suiWiv8F2ADgtK2H9PYwRNg5LomNBKn7j1UbdQP4C7oJ3eYtvA6DCA5KRkgsHOTHY+Kq\r\n /S49D6ajqrN4ZyB+XTLnA5IN8ew=\r\nX-Mailgun-Sending-Ip: 198.61.254.22\r\nX-Mailgun-Sid: WyJlOThhZiIsICJhYV9leHRfdGVzdDAybWdAY29tY2FzdC5uZXQiLCAiMjVhZjRiMyJd\r\nContent-Transfer-Encoding: quoted-printable\r\nReceived: by luna.mailgun.net with HTTP; Fri, 17 Jan 2020 20:18:09 +0000\r\nDate: Fri, 17 Jan 2020 20:18:09 +0000\r\nSender: user@test.domain.com\r\nMessage-Id: <20200117201809.1.82C23D86DE20410C@test.domain.com>\r\nX-Mailgun-Seed-Test-Id: 5e22167af8424f444ca6d8e2\r\nTo: aa_ext_test02mg@comcast.net\r\nFrom: user@test.domain.com\r\nSubject: testSubject\r\nContent-Type: text/html; charset=\"ascii\"\r\nMime-Version: 1.0",
  "message_id": "<20200117201809.1.82C23D86DE20410C@test.domain.com>",
  "time": "2020-01-17T20:18:08.8Z"
}

Field Explanation:

Name Type Description
address string The address used to check for a test message.
provider string The provider responsible for maintaining the address.
ip string The ip the test message was sent from.
folder string The folder the test meassage landed in.
headers string The headers attached to the test message when retrieved from the address
message_id string The unique identifier attached to the test message when it is sent.
time string The time in which the message arrived at the address.