> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Describes the custom database action script for changing a user's email.

# Change Email Script Template

The Change Email script implements the defined function when a user's email address or their email address verification status changes. We recommend naming this function `changeEmail`.

The script is only used in a [legacy authentication scenario](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections), and is required if you want to update a user's email address (and/or email address verification status) in Auth0 and your external database in the same operation.

The Change Email script is not configurable through the <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To manage this script, you must use the Auth0 <Tooltip tip="Management API: A product to allow customers to perform administrative tasks." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip> [Create a connection](https://auth0.com/docs/api/management/v2#!/Connections/post_connections) or [Update a connection](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) endpoint, or the [Auth0 Deploy CLI](/docs/deploy-monitor/deploy-cli-tool).

<Warning>
  If you manage a custom database connection's Database Action Scripts through the Auth0 Dashboard, the Change Email script will be automatically deleted upon saving.

  To ensure that the Change Email script is not removed accidentally, use the Auth0 Management API or Auth0 Deploy CLI when managing the connection.

  If you manually change a user's email in your custom database, you must patch the user separately; Auth0 will not automatically detect the change.
</Warning>

## ChangeEmail function

The changeEmail function should:

* Update the user's email address in the external database.
* Return an error if the operation failed or an error occurred.

### Definition

The `changeEmail` function accepts four parameters and returns a `callback` function:

```js lines theme={null}
changeEmail(email, newEmail, verified, callback): function
```

| Parameter  | Type     | Description                                                       |
| ---------- | -------- | ----------------------------------------------------------------- |
| `email`    | String   | User's current email address.                                     |
| `newEmail` | String   | Value to be set as user's new email address in external database. |
| `verified` | Boolean  | Email verification status of the new email address.               |
| `callback` | Function | Used to pass error data through the pipeline.                     |

### Example

This is a pseudo-JavaScript example of how you could implement the `changeEmail` function:

```javascript lines expandable theme={null}
function (email, newEmail, verified, callback) {
  // Prepare the API call
  let options = {
    url: "https://example.com/api/users",
    action: "PATCH",
    body: {
      email: email,
      new_email: newEmail,
      email_verified: verified
    }
  };

  // Call the API
  send(options, err => {
    // Return `false` value in callback if operation failed
    if (err && err.id == "FAIL_CHANGE_EMAIL") {
      return callback(null, false);
    } else if (err) {
      // Return error in callback if unspecified error occurred
      return callback(new Error("My custom error message."));
    }

    // Return `true` value in callback if operation succeeded
    return callback(null, true);
  });
}
```

## Callback function

The `callback` function accepts two parameters and returns a function.

### Definition

```js lines theme={null}
callback(error, operationResult): function
```

| Parameter         | Type    | Required | Description                                         |
| ----------------- | ------- | -------- | --------------------------------------------------- |
| `error`           | Object  | Required | Contains error data.                                |
| `operationResult` | Boolean | Optional | Indicates the result of the change email operation. |

### Return a success

If the change email operation succeeded, return the `callback` function, and pass a `null` value as the `error` parameter and a `true` value as the `operationResult` parameter:

```js lines theme={null}
return callback(null, true);
```

### Return a failure

If the change email operation failed, return the `callback` function, and pass a `null` value as the `error` parameter and a `false` value as the `operationResult` parameter:

```js lines theme={null}
return callback(null, false);
```

### Return an error

If an error occurred, return the `callback` function, and pass relevant error information as the `error` parameter:

```js lines theme={null}
return callback(new Error("My custom error message."));
```

## Learn more

* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)