When you run an inbox placement test, Mailgun identifies which emails arriving at our seed addresses belong to your test. This article explains the two matching methods available and why header-based matching is recommended.
Header-Based Matching (Recommended)
The preferred method for matching emails to your test is to include the test's unique ID in an email header. Header-based matching is both more accurate and faster than subject-based matching, and it works reliably even when your campaign uses personalized or dynamic subject lines.
To use header-based matching, add the X-MG-IBP-ID header to your email with the test's unique ID:
X-MG-IBP-ID: <uniqueID>
Example: Adding the Header via the Mailgun API
When sending through the Mailgun API, prefix any custom header with h:. Here's an example of sending a message with the X-MG-IBP-ID header included:
curl -s --user 'api:YOUR_API_KEY' \ https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \ -F from='Newsletter <newsletter@YOUR_DOMAIN_NAME>' \ -F to='recipient@example.com' \ -F subject='Your August Product Update' \ -F html='<html>Here is what is new in August...</html>' \ -F h:X-MG-IBP-ID='a7393744-f79b-45cf-8330-fdc058fef3c1'
If you send via SMTP or another email service provider, add X-MG-IBP-ID using your client's or provider's custom header option — any method that adds the header to the outgoing message will work.
When this header is present and contains a valid test ID, it takes precedence over subject-based matching, ensuring your results are attributed correctly and processed as quickly as possible.
Subject-Based Matching
If the X-MG-IBP-ID header is not included, emails are matched to your test using a combination of:
- Sender address — the From address of the email
- Subject line — the subject of the email
- Send time — when the email was sent, relative to when the test was created
Subject-based matching requires no additional configuration. Send your email to the provided seed list using the same sender and subject you registered with the test, and results will populate automatically.
Limitations of Subject-Based Matching
Subject-based matching relies on the subject line being consistent across all seed addresses. If your campaign uses personalized subject lines (for example, Alex, your August product update is here), each seed receives a different subject, and the emails may not be matched to your test. In these cases, header-based matching is required for reliable results.
Which Method Should I Use?
| Scenario | Recommended Method |
|---|---|
| You can add a custom header to your email | Header-based matching (fastest and most accurate) |
| Personalized or dynamic subject lines | Header-based matching (required for reliable matching) |
| Custom headers are not an option | Subject-based matching (sender, subject, and send time) |
FAQ
What happens if the header is missing or contains an invalid ID? Mailgun will fall back to subject-based matching using sender, subject, and send time.
Does the header affect deliverability? No. Custom headers like X-MG-IBP-ID are standard practice and do not impact how mailbox providers handle your message.
Can other headers be used for matching? Yes. Mailgun can also match emails using certain campaign and message identifier headers commonly added by email platforms, including:
X-MAILJET-CAMPAIGNX-JOBX-JOBIDX-CIDX-CAMPAIGN-IDX-CAMPAIGNIDX-CAMPAIGN_IDX-LISTIDX-MAILINGID
However, X-MG-IBP-ID is the recommended header for inbox placement testing — it's purpose-built for this feature and provides the most reliable matching. If your emails already include one of the headers above, no action is needed, but adding X-MG-IBP-ID ensures the most accurate results.