Introduction

An Inbox Placement test (seed test) shows where your email lands — inbox, spam, or missing — across major mailbox providers, including which Gmail tab it was placed in.

There are three ways to run a test. Choose based on how you send:

To start a Simplified or Advanced test, go to Optimize → Inbox Placement in the Mailgun Control Panel, start a new test, and choose the Simple Test or Advanced test tab.

Tip: You can test before, during, or after your campaign, but testing during the campaign gives the most accurate results.

Results usually appear within a few minutes on the Inbox Placement overview page.

Note: Inbox Placement is included with Mailgun Optimize plans. Each test counts toward your plan's monthly test allowance.

Simplified testing

Use this if you have a domain added to Mailgun with verified DNS.

Step 1: Designate sender

1. Enter the From address: type the user name, then select your sending domain.
2. Enter a Sender name.
3. Choose a Sending IP: your default IP, a specific IP, or an IP pool.
4. Click Continue.

Step 2: Create test content

1. Choose Custom HTML, or Select template from Mailgun and pick a domain-level or account-level template.
2. Enter a Subject line.
3. Check the Preview tab, then click Continue.

Personalization: If you're sending with a Mailgun template, you can insert each seed address's first and last name with %recipient.first_name% and %recipient.last_name%.

Step 3: Select providers

1. All providers are selected by default. Uncheck any you want to exclude.
2. Click Start test. Mailgun sends the message to the seed addresses for you.

Using the API with Simplified Testing

You can also run a simplified test through the API instead of the Control Panel. Send a request to POST /v4/inbox/tests that includes:

• from and subject
• either html or template_name
• (optional) provider_filter to test only certain providers
• (optional) seed_list to reuse an existing seed list

For the full parameter list and examples, see the Run Inbox Placement Test API documentation.

Advanced testing

Use this if you send outside of Mailgun, or you want to add the seed list to your own contact list. You send the emails to the seed list yourself.

Step 1: Designate seed list

1. Choose an existing seed list, or enter a name to create a new one.
2. Click Continue.

Tip: Reuse one seed list for each recurring campaign (for example, one for your weekly newsletter). Every test creates a new report under that seed list, so you can compare runs over time.

Step 2: Select providers (new seed lists only)

1. All providers are selected by default. Uncheck any you want to exclude.
2. Click Continue.

If you chose an existing seed list, this step is skipped and you go straight to Step 3.

Step 3: Send to the seed list

1. Click Download addresses, or copy the addresses from Seed list addresses.
2. Add them to your campaign's recipient list in your ESP and send as usual.

Important: Send to the entire list, especially the first address. It's unique to your account and required to generate a test. Seeds that don't receive your message are counted as Missing.

Tip: If you plan to send several tests in quick succession, add the X-MG-IBP-ID header to improve accuracy. See How your emails are matched.

Send API Test

If you send through the Mailgun API, you can add o:inbox-placement-test-key to a normal send request. Your message goes to its recipients as usual, and Mailgun automatically sends a copy to the full seed list. For a full walkthrough, see Running an Inbox Placement Test via the Send API.

curl -s -X POST \
  -u "api:YOUR_API_KEY" \
  https://api.mailgun.net/v3/YOUR_DOMAIN/messages \
  -F from='Test <postmaster@YOUR_SANDBOX_DOMAIN>' \
  -F to="customer@example.com" \
  -F subject="March Newsletter" \
  -F html="<h1>Hello!</h1><p>Here's what's new this month.</p>" \
  -F o:inbox-placement-test-key="newsletter-2026-03-a7f3"

The key is an idempotency key:

• Only one test runs per key within 7 days; repeat sends or retries with the same key don't use extra tests.
• Up to 100 keys are stored per account. New tests won't be created once the limit is reached until older keys expire.
• Use a stable key per campaign (e.g. your campaign ID), and a new key for each new run.

For the full parameter reference, see the Send API documentation for o:inbox-placement-test-key.

Receiving the results

Results appear on the reports page within a few minutes. If results are missing or incomplete, first make sure your emails have finished sending to every address on the seed list before troubleshooting further.

Open a result to see:

• AI analysis: a summary of your content and deliverability. Click More detail for the full analysis.
• Overall placement: Inbox, Missing, and Spam rates, plus an overall score (Low to High).
• Gmail folder placement: the share of Gmail seeds that landed in Primary, Promotions, Social, Forums, Updates, or Spam.
• Preview: the email as it was received.
• Spam feedback: your SpamAssassin score. Click Details to see which rules affected it.
• Microsoft spam scoring: your Bulk Complaint Level (BCL) and Spam Confidence Level (SCL).
• Authentication: SPF, DKIM, and DMARC results.
• Providers breakdown: delivery delta, score, Inbox/Missing/Spam rates, and security status for each provider. Expand a provider, or click Expand All, for more detail.

The top of the report shows the sender, test ID, and delivery delta. To share the report with teammates or stakeholders, click Edit sharing.

Note: A seed is only marked Missing after no message arrives for 24 hours. 

Troubleshooting

No results after sending (Advanced testing)

• Confirm you sent to the unique ID address. Without it, no results are generated.

No results (Send API)

• Check whether the o:inbox-placement-test-key was already used in the last 7 days, or whether you've reached the 100-key limit.

High Missing rate

• Missing usually means the seed bounced or was never sent. Confirm the full seed list was included and allow 24 hours.
• If you used personalized subject lines without a matching header, we will not be able to match emails to your results. Add the X-MG-IBP-ID header to improve matching. View How Emails Are Matched to Inbox Placement Tests to learn more about how emails are matched to results.

Need Support?

Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!