# Send Auth0 email with Groundmail

Auth0's built-in email service is meant for testing: it has low limits and sends from Auth0's own address. Set Groundmail as your tenant's email provider and Auth0's emails (verification, password reset, welcome, MFA enrollment, blocked account and passwordless codes) come from your own domain and show up in your Groundmail email log with delivery status.

---

## Prerequisites

- A Groundmail account with a [verified sending domain](https://docs.groundmail.dev/domains). A subdomain such as `mail.yourdomain.com` works well.
- An Auth0 tenant, and a role that can create applications in it.

---

## 1. Create a Machine to Machine application in Auth0

Groundmail sets the email provider through the Auth0 Management API, using an application you create and control.

1. In the Auth0 Dashboard, go to **Applications → Applications** and click **Create Application**.
2. Name it `Groundmail`, choose **Machine to Machine Applications**, and click **Create**.
3. Select **Auth0 Management API**.
4. Under **Permissions**, filter for `email_provider` and tick exactly these three:
   - `read:email_provider`
   - `create:email_provider`
   - `update:email_provider`
5. Click **Authorize**.
6. Open the application's **Settings** tab and keep it open. You need its **Domain**, **Client ID** and **Client Secret**.

The application can only read and change your email provider. It can't see your users or change anything else in the tenant.

---

## 2. Connect Auth0 in Groundmail

1. In the dashboard, open **Integrations → Auth0**.
2. Paste the **Domain** (for example `acme.us.auth0.com`), **Client ID** and **Client Secret**.
3. Enter a sender address on your verified domain, such as `noreply@yourdomain.com`. To show a name in the inbox, set the **From** field on your Auth0 email templates (**Branding → Email Templates**), for example `Acme <noreply@yourdomain.com>`.
4. Click **Connect Auth0**.

Groundmail checks the application by getting a Management API token and reading your current email provider. Then it creates an SMTP credential and sets your tenant's email provider to SMTP with it. If the tenant already uses another email provider, Groundmail asks before replacing it.

Use your tenant's `auth0.com` domain, as shown on the application's Settings tab, even if your users sign in on a custom domain. Groundmail only sends your client secret to that domain. The secret is stored encrypted, and Groundmail gets a short-lived token each time it changes your provider.

The credential is listed under **SMTP** as "Auth0: *your tenant domain*", where you can revoke it. The password never appears on screen.

### Change the sender

Open **Integrations → Auth0**, edit the sender address or name, and click **Save sender**. Groundmail updates your tenant with a new SMTP credential and revokes the old one.

Auth0 uses the sender as the **From** address for every email that doesn't set its own. An email template with its own **From** address under **Branding → Email Templates** keeps using that address.

### Disconnect

**Disconnect** makes Groundmail forget the application's credentials. It doesn't change your tenant: Auth0 keeps sending through Groundmail. To stop, in Auth0 go to **Branding → Email Provider** and turn off **Use my own email provider**, or choose another provider. Then revoke the "Auth0: …" credential under **SMTP**. You can also delete the Groundmail application in Auth0.

---

## By hand

Create an SMTP credential under **SMTP**. Then in the Auth0 Dashboard go to **Branding → Email Provider**, turn on **Use my own email provider**, choose **SMTP Provider**, and enter:

| Setting | Value |
|---------|-------|
| From | An address on your verified domain, for example `Acme <noreply@yourdomain.com>` |
| Host | `smtp.groundmail.dev` |
| Port | `587` |
| Username | `groundmail` |
| Password | The SMTP credential |

Click **Save**.

---

## Check it works

On **Branding → Email Provider** in Auth0, click **Send Test Email**, or trigger a password reset for a test user. The email appears under **Emails** in the Groundmail dashboard with its delivery status. If it doesn't arrive, check **Monitoring → Logs** in Auth0 for a failed email event.