Tutorials · 2026
2026: How to Integrate the Mailgun Inbox Placement Test API Into CI?
For CI maintainers, QA engineers, and indie developers testing email from their own products, this guide explains what an Inbox Placement test can prove and what it cannot. Follow the request, retry, report, and controlled-inbox acceptance stages to keep seed results separate from end-to-end evidence.
2026: How to Integrate the Mailgun Inbox Placement Test API Into CI?For CI maintainers, QA engineers, and indie developers testing email from their own products, this guide explains what an Inbox Placement test can prove and what it cannot. Follow the request, retry, report, and controlled-inbox acceptance stages to keep seed results separate from end-to-end evidence.
In this article
A Mailgun Inbox Placement test key is retained for seven days, and reusing it during that window does not create a new test, according to Mailgun’s Send API test instructions. So, if Inbox Placement is enabled for your account, add o:inbox-placement-test-key to your normal Send API request and keep the same key for retries of the same activity. Treat the resulting seed report as placement evidence—not as proof that your own user-facing email was received or that its workflow succeeded.
This week: connect one authorized test flow to CI, preserve the key across retries, and keep a controlled-inbox check separate from the seed report.
Who this is for: CI maintainers connecting their product’s mail flow to automated checks.
QA engineers separating seed placement evidence from actual message receipt.
Indie developers who need retries without accidentally creating duplicate tests.
Last updated November 20, 2026. Mailgun API behavior and report guidance checked against the official documentation linked below.
Before CI: decide what the Mailgun Inbox Placement Test API can prove
Start by writing down the claim your pipeline needs to make. “The application built the right verification email” is different from “the message reached the seed list,” and both differ from “a user can receive the message, follow its link, and complete signup.” Those are separate checks, even if they begin with the same send operation.
A seed test tells you about the test configuration and seed environment used for that run. It does not guarantee that every mailbox provider, recipient, or user inbox will handle the message the same way. Nor does an API send response prove that the message is visible in a real recipient’s inbox. Mailgun documents the parameter as a way to associate a normal send with an Inbox Placement test, not as a universal delivery guarantee. See the Send API parameter reference and Inbox Placement send guidance.
Use this scope check before changing your pipeline:
- Application logic only: assert that your app creates the expected message content, recipient, and link. A mock or captured message may be enough; seed placement adds little if you are not checking placement.
- Seed placement: send through the enabled Inbox Placement setup and inspect the report for the associated seed test. This answers a placement question about those test seeds.
- Real user-flow acceptance: receive a message in a controlled address, open it, verify the link, and confirm the expected account state. This is required when your release claim includes the complete flow.
Only run these checks against your own product or a sending environment you are authorized to test. Do not use the pipeline to create accounts on unrelated services.
A simple case helps keep the evidence straight. Your pre-release pipeline sends a signup confirmation from a staging build. The send response says the request was accepted. The seed report later shows how the test seeds handled it. A separate controlled address receives the confirmation and lets the test verify the link and account state. If the final check fails, the seed result does not turn that failure into a pass.
Choose the test by its acceptance claim
| Option | What it can establish | What it cannot establish | Use it when |
|---|---|---|---|
| Application-level message assertion | Your code generated the expected message or payload | Seed placement or receipt in a real inbox | You are testing templates, content, or application logic |
| Inbox Placement seed test | Placement results for the associated test and seed environment | Universal inbox delivery, controlled-address receipt, or a working product flow | You need placement evidence from the configured seeds |
| Controlled inbox end-to-end check | Receipt at the test address and, if tested, link and account behavior | Broad placement across providers or the entire seed environment | You need release evidence for a real product workflow |
The options complement one another rather than replacing one another. A seed report may be the right signal for a placement-focused check, while a controlled inbox is the relevant signal for a verification-link regression. Keep the distinction in CI names and status messages, so a green “seed placement” job cannot be mistaken for a green “signup works” job.
Prepare the send request and make the run traceable
Confirm that Inbox Placement is enabled for the account and that the sending domain and recipient configuration are suitable for your authorized test. The Mailgun instructions for running a test through the Send API describe the required account setup and how the parameter ties a send to a test. Do not assume that a successful request has already produced a complete report.
Add the parameter to the product’s normal send request, rather than creating a parallel message path that bypasses the application behavior you intend to test. A simplified CI request can look like this:
curl --fail-with-body \
--user "api:${MAILGUN_API_KEY}" \
"https://api.mailgun.net/v3/${MAILGUN_DOMAIN}/messages" \
--form-string "from=${TEST_FROM}" \
--form-string "to=${TEST_RECIPIENT}" \
--form-string "subject=${TEST_SUBJECT}" \
--form-string "text=${TEST_BODY}" \
--form-string "o:inbox-placement-test-key=${PLACEMENT_TEST_KEY}"
Use the actual endpoint and request fields supported by your account and implementation; the official Send API parameter documentation is the authority for request syntax. Keep the API credential in your CI secret store, not in source control or logs. Use a test-specific message and recipient so you can identify the run without exposing real personal data.
Make the key and the run traceable together. For example, record a CI run identifier in your job metadata and log the key or a safe reference to it alongside the request outcome. Avoid putting secrets or sensitive recipient data in the test report. The key associates the send with the test; your own run identifier helps your team match CI output, send response, report, and controlled-inbox evidence.
During a run: keep retries idempotent
Mailgun documents a seven-day reuse window for the test key: using the same key again during that period does not create a new Inbox Placement test. The official instructions also document a limit on the number of keys stored for an account. Check the current API test instructions before designing key rotation, since account limits and API guidance should not be inferred from a sample pipeline.
The key behavior is useful when a CI job cannot tell whether a request reached the service. For a network timeout, retry the same logical operation with the same key. If the first attempt was accepted but the response was lost, the stable key prevents that retry from being treated as a request for another test. Do not mint a new key merely because a job restarted.
By contrast, an intentional rerun should have a new key when you need a distinct test and report. A practical distinction is:
- Retry: same build activity, same intended send, same key.
- New test run: a new intentional activity for which you need a separate report, new key.
- Unclear outcome: inspect the request and report evidence before deciding whether the run should be repeated as a new test.
This distinction has a trade-off. Stable keys make network recovery safer, but reusing one for a deliberately new run can leave you looking at an earlier test rather than creating the report you expected. Fresh keys separate intentional runs, but careless key generation can consume the account’s stored-key capacity. Generate keys from a stable activity identity, not from a retry counter or timestamp that changes on every attempt.
After sending: diagnose an incomplete report from evidence
When a report is missing or incomplete, start with the request record rather than immediately sending again. Check that the CI request included o:inbox-placement-test-key, that the intended account and sending configuration were used, and that the key was not already used within its documented reuse window. Then confirm that the send request completed and that the seed messages had an opportunity to be processed.
Next, inspect the report at the level of its seed entries. The Inbox Placement report API documentation describes the report data and statuses. A seed that has not yet received the message is not, by itself, proof that the message was permanently lost. Follow the waiting period and Missing-state criteria in Mailgun’s seed test guidance, rather than failing the job on the first incomplete poll.
Use a timeline in your CI artifact:
- Request record: endpoint, parameter presence, run reference, and request outcome.
- Send response: whether the API accepted the send request. Do not label this “delivered.”
- Placement report: the associated report and the seed statuses available for that run.
- Controlled inbox: whether the separate test address received the message and whether the product flow completed.
This lets you locate the failing boundary. If the send response is absent, investigate the request path and credentials. If the send succeeded but seed entries are pending, follow the report’s documented waiting guidance. If seeds report placement but the controlled address is empty, investigate that recipient path separately. Each result is evidence about a different stage.
At acceptance: keep the report separate from the product check
A release gate should state which evidence it requires. If the gate is about seed placement, make the job name and pass criteria say so. If it is about signup completion, require the controlled address to receive the message and the application to accept the verification action. Do not let a seed report silently stand in for both.
The separation matters for password resets and account verification in particular. A seed placement result cannot show that your message contains the correct user-specific link, that the link resolves to the intended environment, or that the application updates the account after the user follows it. Those checks belong in an authorized end-to-end flow using test data that does not identify a real person.
Mailtock may be one option for a separate controlled-receipt check, but this article does not verify its current address options, registration requirements, retention period, or delivery timing. Do not assume those capabilities from Mailgun’s documentation or from a seed report. Before adopting any test inbox, verify its current terms and behavior directly. If you use an address that can receive your test message, treat that as a separate acceptance path; it does not participate in Mailgun’s seed test unless Mailgun explicitly documents that relationship.
For the same reason, do not use a disposable address for accounts where you will need long-term recovery, ongoing correspondence, or reliable access to sensitive notices. For longer-lived test identities, compare an alias with a disposable address using the team’s retention and access needs; this guide to disposable addresses versus aliases explains the distinction. If a controlled inbox is part of your test design, review how inbox lifespan affects access before relying on it for later runs.
FAQ
How do I trigger an Inbox Placement test from a Mailgun send?
Add o:inbox-placement-test-key to the normal Mailgun Send API request, after confirming that Inbox Placement is enabled for the account. Use a key tied to the CI activity or test run. The request links sending to a seed test; a successful send response alone does not mean that a report is ready or that a real user received the message.
How can CI retries avoid creating duplicate placement tests?
Keep the same key when retrying the same logical send after a timeout or uncertain network response. Mailgun documents that reuse within seven days does not create another test. Create a new key only when you intend to run a distinct test and need a new report. Also account for the limit on stored keys when designing long-running automation.
What should I check if an Inbox Placement report has no results?
Start with the request log: verify the parameter was included and check whether the key was already used within its retention period. Then check whether the seed messages have completed sending and review the report's seed statuses. Follow Mailgun's documented waiting and Missing-state guidance before treating an empty or incomplete report as a failed delivery.
Do I still need to test email verification after seeds show inbox placement?
Yes, if your acceptance goal includes the product workflow. Seed results describe placement in the test's seed environment; they do not prove that your controlled test address received the message, that a verification link works, or that your application changed the account state correctly. Run a separate end-to-end check for those behaviors.
Keep the two acceptance paths explicit
A reliable CI result tells you exactly what passed: the application generated the intended message, the seed report recorded placement for its configured test environment, or a controlled address completed the product flow. Use the same key for retries, create a new one only for a deliberate new test, and avoid treating any one of those signals as a substitute for the others.
If you still need a separate controlled inbox for your own product’s test email, start with Mailtock’s email privacy information and verify the current service details before adding it to your workflow. That keeps the decision bounded: use seed testing for seed placement, and use an independently verified test address for the receipt and verification behavior your product actually needs.
Frequently asked questions
How do I trigger an Inbox Placement test from a Mailgun send?
Add `o:inbox-placement-test-key` to the normal Mailgun Send API request, after confirming that Inbox Placement is enabled for the account. Use a key tied to the CI activity or test run. The request links sending to a seed test; a successful send response alone does not mean that a report is ready or that a real user received the message.
How can CI retries avoid creating duplicate placement tests?
Keep the same key when retrying the same logical send after a timeout or uncertain network response. Mailgun documents that reuse within seven days does not create another test. Create a new key only when you intend to run a distinct test and need a new report. Also account for the limit on stored keys when designing long-running automation.
What should I check if an Inbox Placement report has no results?
Start with the request log: verify the parameter was included and check whether the key was already used within its retention period. Then check whether the seed messages have completed sending and review the report's seed statuses. Follow Mailgun's documented waiting and Missing-state guidance before treating an empty or incomplete report as a failed delivery.
Do I still need to test email verification after seeds show inbox placement?
Yes, if your acceptance goal includes the product workflow. Seed results describe placement in the test's seed environment; they do not prove that your controlled test address received the message, that a verification link works, or that your application changed the account state correctly. Run a separate end-to-end check for those behaviors.
This article offers guidance on managing email for shopping. It doesn’t replace the retailer’s instructions for orders, unsubscribing or privacy requests. Check the relevant service’s policies for specific steps and processing times.