Inbox Placement

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 upload_bulk_validation() {
  $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.