Why not use the public @mailsac.com inboxes?

Any address at @mailsac.com receives mail with no sign-up, which is handy for a quick manual check. For a test suite that runs every day, it causes three problems.

• Anyone can read them. Public inboxes have no password. If your staging app emails real-looking names, one-time codes or reset links, anyone who guesses or reuses the address can see them. Use made-up data in public inboxes.
• They are shared and throttled. Mail to public addresses has a lower throttling threshold than mail to private addresses or verified custom domains. When a CI run sends a burst of email, delivery can first slow down and then be refused with an SMTP 421 error, so tests fail or time out.
• Other people use the same addresses. A public inbox keeps only the latest 6 messages, for up to 4 days, and someone else’s mail can land in it. Some senders also refuse to deliver to @mailsac.com at all.

A private domain avoids all three. Mail on it is visible only to your account and team, is throttled at a much higher threshold (most customers never hit it), and is kept until you delete it or reach your plan’s storage limit.

Sources: Email throttling, Message storage and Missing email in the Mailsac docs.

Set up your own domain: exact DNS records

1. In the dashboard, open Custom Domains, choose Setup a Custom Domain and enter the full domain name, for example qa.example.com.
2. Open the domain’s DNS Setup tab. It shows a TXT value unique to your domain that starts with mailsac_.
3. Add these records at your DNS host:

4. Back on the DNS Setup tab, click Query My DNS Settings Now. Each record shows OK once Mailsac can see it. Both MX records are required.

The MX values are the same for every domain hosted at Mailsac; only the TXT value is unique. Many DNS hosts want the name without your root domain (for example just qa), or @ for the root domain itself.

Amazon Route 53

Create one MX record set for the name with both values on separate lines: 1 in.mailsac.com and 5 alt.mailsac.com. For the TXT record, wrap the value in double quotes. If the name already has a TXT record (an SPF record, for example), add the Mailsac value as another quoted line in the same record set rather than creating a second record.

Cloudflare

Add two MX records with the name qa (or your subdomain), mail servers in.mailsac.com and alt.mailsac.com, and priorities 1 and 5. Add a TXT record with the same name and your mailsac_ value. MX and TXT records aren’t proxied, so there is no orange-cloud setting to change.

Check from a terminal

dig TXT qa.example.com +short
dig MX qa.example.com +short
# expected MX answer:
# 1 in.mailsac.com.
# 5 alt.mailsac.com.

Full guides: Custom domains and DNS verification.

Using the domain from your tests

Authenticate every API request with your API key in the Mailsac-Key header. Here is a Playwright test that signs up on staging with a unique address, waits for the confirmation email and opens its link. Each message in the list includes a links array with the URLs found in the email.

import { test, expect } from '@playwright/test';

const DOMAIN = 'qa.example.com'; // or yourteam.msdc.co
const headers = { 'Mailsac-Key': process.env.MAILSAC_API_KEY! };

test('sign-up sends a confirmation link', async ({ page, request }) => {
  const email = `signup-${Date.now()}@${DOMAIN}`;

  await page.goto('https://staging.example.com/register');
  await page.getByLabel('Email').fill(email);
  await page.getByRole('button', { name: 'Sign up' }).click();

  let messages: any[] = [];
  await expect.poll(async () => {
    const res = await request.get(
      `https://mailsac.com/api/addresses/${email}/messages`, { headers });
    messages = await res.json();
    return messages.length;
  }, { timeout: 60_000 }).toBeGreaterThan(0);

  const link = messages[0].links.find((url: string) => url.includes('/confirm'));
  expect(link).toBeTruthy();
  await page.goto(link!);
});

The same check with curl, for example in a shell step in CI:

# newest messages for one address
curl -s -H "Mailsac-Key: $MAILSAC_API_KEY" \
  "https://mailsac.com/api/addresses/signup-123@qa.example.com/messages"

# newest 10 messages across the whole domain
curl -s -H "Mailsac-Key: $MAILSAC_API_KEY" \
  "https://mailsac.com/api/domains/qa.example.com/messages?limit=10"

Troubleshooting

The domain won’t verify

• Run dig TXT and dig MX on the exact name you added. The records must be on that name, for example qa.example.com, not on example.com.
• Check that the TXT value matches the DNS Setup tab exactly, and that both MX records exist. Mailsac needs both in.mailsac.com and alt.mailsac.com.
• Watch for DNS hosts that append the root domain automatically, which turns qa.example.com into qa.example.com.example.com.
• New records can take up to 24 hours to propagate. Click Query My DNS Settings Now again later; the tab lists what it found.

Mail isn’t arriving

• Messages over 2.5 MB are not accepted.
• Your sending service may be queuing mail. SendGrid and Mandrill often delay sends; with SendGrid, set up sender authentication so mail doesn’t come from a shared sendgrid.net address.
• Check the message isn’t in the spam folder of the Unified Inbox. You can turn the spam filter off in Account Settings.
• If your app sends thousands of messages a minute, you can still be throttled. On Business and higher plans you can request an IP allowlist from the dashboard so your senders are never throttled.

A sender is blocked

Some services refuse to send to @mailsac.com, which is one reason to test on your own domain. Mailsac also blocks mail from social media and streaming services, and from senders that harm the service. If you test for one of those companies, contact support.

Older messages disappear

Messages on custom domains, private addresses and starred messages share your plan’s storage limit (1,000 messages on Indie, 5,000 on Business). When it is full, the oldest messages are recycled. Delete old test mail with the API, or add 5,000 more stored messages for $10 a month.

More help: Missing email.