Overview

You can now trigger an Inbox Placement test directly from the Mailgun Send API using the o:inbox-placement-test-key parameter. This lets you send an email and run an inbox placement test in a single API call, with no separate seed test workflow required.

When a test is triggered this way, Mailgun automatically sends the message to the entire seed list for you.

How to trigger a test

Add o:inbox-placement-test-key to your normal send request with a unique value of your choosing:

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"

Your message is delivered to its recipients as usual, and a copy is sent to the entire seed list to create the inbox placement test. See the Send API reference for full parameter details.

About the test key

The value you pass acts as an idempotency key. A common approach is to use your campaign ID as the key: Mailgun will run only a single inbox placement test for that campaign within a week. Additional sends with the same key will not create additional tests, which also protects you from consuming extra tests due to network retries or duplicate calls.

Limits to keep in mind:

• Key lifetime: Each key is remembered for 7 days. Reusing a key within that window will not create a new test. After 7 days, the key expires and can be reused.
• Keys per account: Up to 100 idempotency keys are stored per account at a time. Once this limit is reached, no new tests will be created until existing keys expire.

Best practice: Use a stable, descriptive key per campaign, such as your campaign ID or a campaign name plus a date (spring-promo-2026-03-15). Use a new key when you want a new test, for example for the next run of a recurring campaign.

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!