Add another email address to a user's account
Account profile management
Clerk · Module
emailAddresses.createEmailAddress
Creates an email address for a specified Clerk user and returns the resulting EmailAddress object. Optional flags can make it primary or mark it verified.
How it works
Call the backend email-address method with the target user's ID and the address to create. Optional flags control whether the new address is primary and whether Clerk marks it verified; the promise resolves to the created EmailAddress resource.
Syntax
function createEmailAddress(params: CreateEmailAddressParams): Promise<EmailAddress>Parameters
| Name | Type | Description |
|---|---|---|
emailAddress | string | The email address to create. |
primary? | boolean | Whether the email address should be the primary email address. Defaults to false unless it is the first email address added to the user. |
userId | string | The ID of the user to create the email address for. |
verified? | boolean | Whether the email address should be verified. Defaults to false. |
Returns
Promise<EmailAddress>
Key points
- The backend method creates and associates a new email address with the user identified by userId.
- Awaiting the promise gives the newly created EmailAddress resource.
- emailAddress supplies the address value that Clerk should create.
- userId identifies the account receiving the new address.
- primary is optional and normally defaults to false, with the documented first-address exception.
- verified is optional and defaults to false.
Common mistakes
- Setting primary to true makes the new address primary; otherwise it defaults to false unless this is the user's first email address.
- Setting verified to true marks the address verified, so use it only when your trusted workflow has established verification.
- The SDK method wraps the BAPI endpoint, so backend usage and authentication context are required.
Example: Create a user email address
const response = await clerkClient.emailAddresses.createEmailAddress({
userId: "user_123",
emailAddress: "testclerk123@gmail.com",
primary: true,
verified: true,
});Creates an email address for the specified user and returns the resulting EmailAddress object.
When to use it
Designate an address as primary
Identity administration
Create an address that an authoritative workflow has already verified
Trusted server-side provisioning
Interview questions
QWhat does emailAddresses.createEmailAddress do?
It creates an email address for a specified user and returns the created EmailAddress object. The required inputs are userId and emailAddress.
Follow-up: What does primary control? It controls whether Clerk designates the new address as the user's primary address; it defaults to false except for the first address.
QWhich parameters does the method accept?
The method accepts emailAddress, userId, and optional primary and verified flags. primary defaults to false unless this is the first address, while verified defaults to false.
Follow-up: How would you avoid incorrectly trusting an address? Leave verified false unless an authoritative workflow has already verified the address.
QWhat does the method return?
The call returns a Promise that resolves to an EmailAddress object. The created address is associated with the user identified by userId.
Follow-up: What lower-level operation does the SDK wrap? It wraps the BAPI POST /email_addresses endpoint.
Related
EmailAddressclerkClientCreateEmailAddressParamsuserIdemailAddress