Receive test mail on your own domain

What it is

Instead of anything@qa.acme.mailpier.io, your systems can send test mail to an address on a domain you own, such as anything@mail-test.acme.com. MailPier receives it and shows it in your inbox and through the API exactly like mail on the MailPier domains. Own domains are part of the Team plan (one domain) and the Business plan (up to 5) (see /pricing). If the plan later allows fewer, the oldest domains keep working and the newer ones are kept but inactive (mail to them is refused) until you remove some or change plans. The MailPier domains keep working as well.

On an own domain the account is implied by the domain, so addresses are shorter:

Address	Goes to
`anything@mail-test.acme.com`	`main` (the account-wide inbox)
`anything@qa.mail-test.acme.com`	environment `qa` (and `main`)
`jane.doe@contoso.com.qa.mail-test.acme.com`	environment `qa`, shown as "intended for jane.doe@contoso.com"
`anything@qaa.mail-test.acme.com`	`main`, marked "sent to unknown environment qaa" (a typo is never refused)

1. Choose the domain

Always use a subdomain that receives no real mail, for example mail-test.acme.com or qa-mail.acme.com. Never use your company's mail domain (acme.com) or any name your people or customers receive mail on. The setup replaces the domain's MX records, which decide where ALL mail for that name goes: on your real mail domain, your company's real mail would be delivered to MailPier test inboxes instead of your mailboxes.

You need to be able to edit the DNS records of the parent domain (here acme.com) at your DNS provider. The name must not be a MailPier domain, and it cannot be one another MailPier Inbox account already uses.

2. Add it in Settings

Sign in as an account admin (an owner of main) and open main, then Settings.
Under Your own domain, enter the domain (for example mail-test.acme.com) and press Add.
The panel now shows the domain as Pending and lists the exact records to create, with your own verification token. Copy them from there: the token below is only a placeholder.

3. Create the DNS records

Create five records (two MX for the name, two MX for its wildcard, one TXT). With mail-test.acme.com:

Host (full name)	Host at most providers	Type	Value	Priority	TTL
`mail-test.acme.com`	`mail-test`	MX	`mx1.mailpier.io`	10	3600 (or Auto)
`mail-test.acme.com`	`mail-test`	MX	`mx2.mailpier.io`	10	3600 (or Auto)
`*.mail-test.acme.com`	`*.mail-test`	MX	`mx1.mailpier.io`	10	3600 (or Auto)
`*.mail-test.acme.com`	`*.mail-test`	MX	`mx2.mailpier.io`	10	3600 (or Auto)
`_mailpier.mail-test.acme.com`	`_mailpier.mail-test`	TXT	`mailpier-verify=<your token from Settings>`	–	3600 (or Auto)

MX for the name (mail-test): mail to anything@mail-test.acme.com comes to MailPier.
MX for the wildcard (*.mail-test): mail to every environment, such as anything@qa.mail-test.acme.com, comes to MailPier. Without it, environment addresses bounce.
TXT (_mailpier.mail-test): proves the domain is yours. The domain receives mail only once this record is found.

Most DNS providers want the host relative to your zone (mail-test, *.mail-test, _mailpier.mail-test) and add .acme.com themselves; if you type the full name there, some providers create mail-test.acme.com.acme.com. Enter the TXT value without quotes unless the provider asks for them (Route 53 and zone files do). Mail exchangers are written without http, and a trailing dot is fine where the provider shows one.

Cloudflare

Select the zone acme.com, then DNS, Records, Add record.
Type MX, Name mail-test, Mail server mx1.mailpier.io, Priority 10, TTL Auto. Save. Repeat with mx2.mailpier.io.
The same two MX records with Name *.mail-test.
Type TXT, Name _mailpier.mail-test, Content mailpier-verify=<token>, TTL Auto.

MX and TXT records are always "DNS only" in Cloudflare (no orange cloud); that is correct. If a proxied A or CNAME record already exists for mail-test, see the troubleshooting section.

GoDaddy

My Products, then DNS next to acme.com (Domain settings, DNS records), then Add New Record.
Type MX, Name mail-test, Value mx1.mailpier.io, Priority 10, TTL 1 hour. Save. Repeat with mx2.mailpier.io.
The same two MX records with Name *.mail-test.
Type TXT, Name _mailpier.mail-test, Value mailpier-verify=<token>, TTL 1 hour.

Namecheap

Domain List, Manage next to acme.com, then Advanced DNS.
Under Mail Settings choose Custom MX (MX records cannot be added otherwise). Check first that this does not remove MX records your real mail needs; add those back as Custom MX records if it does.
Add New Record, MX Record: Host mail-test, Value mx1.mailpier.io, Priority 10, TTL Automatic. Repeat with mx2.mailpier.io.
The same two MX records with Host *.mail-test.
Under Host Records, Add New Record, TXT Record: Host _mailpier.mail-test, Value mailpier-verify=<token>.

AWS Route 53

Hosted zones, the zone acme.com, Create record.
Record name mail-test, Record type MX, Value (one per line, priority first):
```
10 mx1.mailpier.io
10 mx2.mailpier.io
```
TTL 3600, Routing policy Simple.
The same record with Record name *.mail-test.
Record name _mailpier.mail-test, Record type TXT, Value with quotes: "mailpier-verify=<token>", TTL 3600.

Azure DNS

In the Azure portal open DNS zones, the zone acme.com, then + Record set.
Name mail-test, Type MX, TTL 1 hour; add two rows: Preference 10 / Mail exchange mx1.mailpier.io and Preference 10 / Mail exchange mx2.mailpier.io.
The same record set with Name *.mail-test.
Name _mailpier.mail-test, Type TXT, TTL 1 hour, Value mailpier-verify=<token>.

4. Verify

Back on main's Settings page, press Check now. It looks up the records and shows what it found for each.

Status	Meaning
Pending	Added; the TXT record has not been found yet. Mail to the domain is refused. MailPier checks again every 15 minutes for 7 days.
Verified	The TXT record was found. Mail to the domain and its environments is accepted (within your plan's limits).
Failed	Not found within 7 days; no more automatic checks. Fix the records and press Check now.

New records are usually visible within a few minutes; some providers take up to an hour, and a changed record can take as long as its old TTL. You can check from your own computer (asking a public resolver avoids your local cache):

# Windows (Command Prompt or PowerShell)
nslookup -type=MX mail-test.acme.com 1.1.1.1
nslookup -type=MX qa.mail-test.acme.com 1.1.1.1
nslookup -type=TXT _mailpier.mail-test.acme.com 1.1.1.1

# PowerShell
Resolve-DnsName mail-test.acme.com -Type MX -Server 1.1.1.1
Resolve-DnsName _mailpier.mail-test.acme.com -Type TXT -Server 1.1.1.1

# macOS / Linux
dig +short MX mail-test.acme.com @1.1.1.1
dig +short MX qa.mail-test.acme.com @1.1.1.1
dig +short TXT _mailpier.mail-test.acme.com @1.1.1.1

The MX lookups must list only mx1.mailpier.io and mx2.mailpier.io (the qa lookup proves the wildcard), and the TXT lookup must show mailpier-verify= with your token. Then send a test mail to hello@mail-test.acme.com from any mail program; it appears in main within seconds.

5. Environments and test databases

Every environment of the account receives on the own domain at once: environment qa gets anything@qa.mail-test.acme.com, and its members and API keys see only that mail; main sees all of it. POST /v1/addresses with {"domain":"mail-test.acme.com"} returns a fresh address on it. To point a copy of a production database at an environment while keeping every real address whole:

-- Run on the TEST copy only. jane.doe@contoso.com -> jane.doe@contoso.com.qa.mail-test.acme.com
-- Skips NULL, empty and non-addresses, and is safe to run twice.
UPDATE dbo.Customers
SET Email = LTRIM(RTRIM(Email)) + '.qa.mail-test.acme.com'
WHERE Email LIKE '%_@_%'
  AND Email NOT LIKE '%.qa.mail-test.acme.com';

6. Troubleshooting

Check now says "TXT not found"

Look up _mailpier.mail-test.acme.com with the commands above. Common causes: the host was entered as the full name and became _mailpier.mail-test.acme.com.acme.com; the value has extra spaces or quotes inside it; the record is not saved or not published yet; or the token was copied from an older entry (removing and adding a domain makes a new token).

"TXT found but with a different value"

The record exists but holds another token. Copy the value again from Settings and replace it.

MX shows other servers ("not MailPier")

Another MX record exists for the name (often inherited from a template or a mail product). Remove every MX record of mail-test except mx1.mailpier.io and mx2.mailpier.io; otherwise part of the mail goes to the other server.

Mail to anything@mail-test.acme.com arrives, but environment addresses bounce

The wildcard MX records (*.mail-test) are missing. Check with nslookup -type=MX qa.mail-test.acme.com 1.1.1.1. Also make sure no other record exists for that exact environment name (a specific record hides the wildcard).

A CNAME at the name blocks the MX records

A name with a CNAME record cannot have any other record, so the MX records are ignored or cannot be saved. Remove the CNAME for mail-test (and for *.mail-test), or choose another name that is not used yet.

Mail is refused with 550

MailPier refuses mail to a domain that is Pending, Failed or removed, to an account whose plan has no own domains (Free, Starter), to a domain beyond the plan's count (marked "inactive" on Settings), and to an account over its monthly message quota. Check the domain's status on Settings and your plan and usage on Billing.

Do I need DNSSEC, CAA, SPF or DKIM records?

No. Receiving test mail needs only the MX and TXT records above. DNSSEC may stay on; CAA records are about certificates and are not involved. SPF and DKIM are about sending mail, which MailPier does not do from your domain.

How long until it works?

Usually a few minutes after the records are published. Press Check now once the commands above show them; the domain receives mail as soon as it is Verified (MailPier checks the TXT record too, within a few minutes).

7. Removing the domain

On main's Settings page press Remove next to the domain and type its name to confirm. From then on mail to it is refused.
Delete the five DNS records at your DNS provider, so no mail is sent to MailPier for that name any more.

Mail already received on the domain is not deleted at once: it stays visible until its environment's retention period ends and is then permanently deleted as usual. The name can be added again later (by this or another account) and gets a new token.

Back to the quick start