DEV Community

Lalit Kumar Jangid
Lalit Kumar Jangid

Posted on Fully Autonomous

Emails to @privaterelay.appleid.com bounce until you do this

You add Sign in with Apple to your app. Sign-in works. Then you notice that some users never get the welcome email, the receipt or the password reset, and your email provider shows a bounce for each of them. Every one of those addresses ends in @privaterelay.appleid.com.

Nothing is broken in your code. Apple's relay is doing what it was built to do: it only forwards email from senders you have registered with Apple, and it rejects everything else. This post covers what to register, how to find the domain most people miss, and how to test the fix.

What a relay address is

When a user picks "Hide My Email" during Sign in with Apple, your app does not get their real address. It gets a random one:

dpdcnf87nu@privaterelay.appleid.com
Enter fullscreen mode Exit fullscreen mode

Apple forwards mail sent to that address to the user's real inbox. The address is unique to that user and to your developer account. You store it like any other email address and send to it like any other.

The catch is that the relay has an allow list, and the list starts empty.

Why the bounce happens

The relay accepts an email only if it comes from a source registered in your Apple Developer account, and only if that email passes authentication. If either check fails, you get a bounce.

In practice there are four causes:

  1. You never registered any email source. This is the usual one.
  2. You registered acme.com but send from mail.acme.com. A subdomain is a separate source.
  3. You registered the domain in your From address but not the domain in your Return-Path.
  4. SPF fails for the registered domain, or the email has no DKIM signature for your From domain.

Cause 3 is the one that survives a first attempt at fixing this, so it gets its own section.

The domain you cannot see: Return-Path

Every email has two sender addresses.

Address Where it is Who sees it
From The From: header Your user
Return-Path The SMTP MAIL FROM, where bounces go Mail servers only

When you send through an email provider, the Return-Path is often on a different domain from your From address. Apple checks SPF against the Return-Path domain, and that domain must be registered and must match exactly.

To find yours, send any email from your app to a mailbox you own and open the raw message. In Gmail that is the three-dot menu, then "Show original". Look for these lines:

Return-Path: <0100018f3c2e-7d1a@bounce.mail.acme.com>
From: Acme <hello@acme.com>
DKIM-Signature: v=1; a=rsa-sha256; d=acme.com; s=abc123; ...
Authentication-Results: mx.google.com;
       dkim=pass header.i=@acme.com header.s=abc123;
       spf=pass smtp.mailfrom=bounce.mail.acme.com;
       dmarc=pass header.from=acme.com
Enter fullscreen mode Exit fullscreen mode

Three values matter:

  • header.from is your From domain: acme.com
  • smtp.mailfrom is your Return-Path domain: bounce.mail.acme.com
  • header.i or d= is your DKIM signing domain: acme.com

If smtp.mailfrom shows your provider's domain, such as amazonses.com or sendgrid.net, you are using the provider's shared Return-Path. You cannot register a domain you do not own, so in that case the email has to pass on DKIM instead: it must be signed with a d= value that matches your From domain exactly. Setting up a custom Return-Path (often called a custom MAIL FROM domain) and custom DKIM with your provider fixes both.

You can check the DNS side from a terminal:

# SPF for the Return-Path domain
dig +short TXT bounce.mail.acme.com

# The DKIM public key (selector comes from s= in the DKIM-Signature header)
dig +short TXT abc123._domainkey.acme.com
Enter fullscreen mode Exit fullscreen mode

An SPF answer looks like "v=spf1 include:amazonses.com ~all". A DKIM answer is a long "v=DKIM1; k=rsa; p=..." string, or a CNAME to your provider.

Registering your sources with Apple

  1. Sign in to your Apple Developer account and open Certificates, Identifiers & Profiles.
  2. Choose Services in the sidebar, then Configure under Sign in with Apple for Email Communication.
  3. Under Email Sources, press the add button.
  4. Enter every domain and subdomain you send from, separated by commas. For the example above that is:
acme.com, bounce.mail.acme.com
Enter fullscreen mode Exit fullscreen mode
  1. Save.

If you do not own the domain you send from, you can register individual email addresses instead.

There is a cap on the number of sources: 32 for an individual membership and 100 for an organization. That is per account, so a team with many apps and many sending subdomains should plan which ones they really need. (Steps and limits are from Apple's developer help page for the private email relay service, checked on November 13, 2026.)

The authentication rules

  • Every registered domain needs an SPF record.
  • Each email must pass SPF or DKIM. Apple recommends both.
  • For SPF, the Return-Path domain must be registered and must pass for the server that sent the email.
  • For DKIM, the d= domain must match the From domain exactly, and the From header must be covered by the signature.

Use both. Forwarding is what a relay does, and forwarding is exactly the case where SPF tends to break and DKIM tends to survive.

Test it properly

Do not test with your normal Apple ID address. Test with a real relay address:

  1. Sign in to your own app with Sign in with Apple and choose to hide your email.
  2. Read the relay address your backend stored for that account.
  3. Send it the same email your app sends, from the same sender and through the same provider.
  4. Check your real inbox, then check the status in your provider's log.

A small script makes this repeatable. This one uses a plain HTTP email API; swap in your provider's endpoint and fields.

// test-relay.mjs
// Usage: RELAY=abc123@privaterelay.appleid.com node test-relay.mjs
const response = await fetch(process.env.EMAIL_API_URL, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAIL_API_KEY}`,
    'Content-Type': 'application/json',
    // Same key on every retry, so a retry can never send a second copy.
    'Idempotency-Key': `relay-test/${process.env.RELAY}`,
  },
  body: JSON.stringify({
    from: 'Acme <hello@acme.com>',
    to: process.env.RELAY,
    subject: 'Relay test',
    text: 'If you can read this, the Apple relay accepts our mail.',
  }),
});

console.log(response.status, await response.json());
Enter fullscreen mode Exit fullscreen mode

Then look up the message in your provider's log. delivered means Apple's relay accepted it. bounced means one of the four causes above still applies.

Two things that bite later

Suppression lists. Most providers stop sending to an address after a hard bounce. If relay addresses bounced for weeks before you registered your domains, those users may now be on your suppression list, and they will keep getting nothing after the fix. Check the list and remove the relay addresses that bounced for this reason.

Changing provider. A new provider means a new Return-Path domain and often a new DKIM setup. Add the new domains to Apple before you switch traffic, not after the first bounce report.

When it is not your fault

A user can turn off forwarding for your app in their Apple Account settings, or stop using Sign in with Apple with your app. Mail to that relay address then no longer reaches them, and no amount of registering domains will change it. If email matters to your product, let users add a contact address in their profile.

Checklist

  1. Send yourself a real email and read header.from, smtp.mailfrom and the DKIM d= value.
  2. Make sure the Return-Path is on a domain you own. Set up a custom MAIL FROM if it is not.
  3. Make sure DKIM signs with your From domain.
  4. Register the From domain and the Return-Path domain with Apple. Subdomains count separately.
  5. Test with a real relay address, not your own inbox.
  6. Clear relay addresses that bounced earlier from your suppression list.
  7. Repeat steps 1 to 4 whenever you change email provider.

We build Cresca, an email platform for transactional email and marketing campaigns. It signs mail with DKIM for your own domain and uses a custom MAIL FROM subdomain on that domain, so there are two entries to register with Apple and both are yours. The short version of this guide lives in our docs: Emails to privaterelay.appleid.com. If you hit a relay bounce that does not fit these four causes, tell us in the comments.

Top comments (0)