The Ultimate Guide: Updating Your Users' Email Domain

[#1]

👋 This guide offers detailed instructions for Organization Admins on migrating from one email domain to another, along with the necessary steps to update the email addresses of their Managed Accounts on Atlassian Administration (admin.atlassian.com).

Cloud only.

Description

In certain situations, a company may acquire or be acquired by another organization, requiring a transition from one email domain to another. This process involves updating the email addresses associated with Atlassian Accounts.

When an account is considered claimed and managed by an Atlassian Organization, only Organization Admins are able to update a user’s email address/domain.

Prerequisites checklist

Before we can begin updating email addresses, it is essential to ensure that all necessary preparations are in place. Below is a list of requirements that must be fulfilled before proceeding with any changes.

Domain verification: Both email domains (original and new) must be verified under the same Atlassian Organization. You may choose to verify a domain using a couple of methods such as TXT records via DNS, HTTPS verification, through Google Workspace, etc. Instructions on how to verify a domain can be found here.

Claiming Atlassian Accounts: Related to the above on domain verification, accounts (with the original email address) must be claimed by the Organization that verified both domains. Instructions on how to claim accounts can be found here.

New email address must be available: An email address must be unique and can only be associated with one Atlassian Account. This means that if the email address you wish to use is already linked to another Atlassian Account, the attempt to change the email for that specific user will not be successful.

For example: The Organization Admin intends to change the email address from user1@owlpostmail.com to user1@hogwartsmail.net. However, User1 has inadvertently created a new Atlassian Account using the hogwartsmail.net email address, resulting in two separate Atlassian Accounts: one associated with owlpostmail.com and the other with hogwartsmail.net. When the Organization Admin attempts to change the email address, they encounter the following error message: Someone is already using this email. Try another.

For instructions on verifying email address availability and resolving issues with unavailable addresses, please refer to 'How do I check if all new email addresses are available, and how do I deal with such accounts?' the FAQ section located at the bottom of the page.

Executing the email changes

After verifying the domains and ensuring that all Atlassian Accounts are claimed without any duplicates, you can move forward with the email changes. Below, I outline three methods for updating email addresses: individual email changes, a bulk option and through an Identity Provider (in case of Atlassian Guard).

Individually

This option is ideal for updating a limited number of Managed Accounts that are not synchronized with an Identity Provider:

1. Go to Atlassian Administration.

2. Select Directory > Managed accounts.

3. Select a user to open the managed accounts page.

4. Select the email address field and enter the updated email address.

5. A confirmation message appears when the update has been successful.

More information and context can be found here.

Bulk update

In case, you have a substantial number of Managed Accounts that are not synced through an identity provider.

Unfortunately, Atlassian Administration’s UI currently doesn't have a feature for performing bulk changes to Managed Accounts. We have submitted a feature request to potentially implement this functionality in the future. If you are comfortable with coding, an alternative solution is to write/run a script utilizing the SET Email REST API endpoint.

Below is an example Bash script suitable for Linux or Mac systems:

#!/bin/bash
# Your existing variable setups
API_KEY="API_TOKEN"
CSV_FILE="email_change.csv"
# Verify the file exists
if [ ! -f "$CSV_FILE" ]; then
    echo "File not found: $CSV_FILE"
    exit 2
fi
# Read the CSV file (skipping the header), and for each line, extract account_id and email
tail -n +2 "$CSV_FILE" | while IFS=, read -r account_id email_raw; do
    # Remove carriage return character from email
    email=$(echo "$email_raw" | tr -d '\r')
    echo "Updating email for account_id: $account_id with email: $email"
    # Prepare JSON data using jq
    json_data=$(jq -n --arg email "$email" '{email: $email}')
    # Run the curl command with the variables
    curl --request PUT \
        --url "https://api.atlassian.com/users/${account_id}/manage/email" \
        --header "Authorization: Bearer ${API_KEY}" \
        --header 'Content-Type: application/json' \
        --data "$json_data"
done
echo "Done."

Depending on the separator character you choose for your CSV files—whether it's a comma or a semicolon—you may need to modify the IFS parameter (line 12) to match the separator.

To execute the above script mentioned above, you'll need to gather three components:

• API Key: This can be obtained from admin.atlassian.com by navigating to Settings > API Keys. Requires Organization Admin permissions. You can paste it onto the API_KEY variable.

• CSV File: Prepare a CSV file that includes two columns with the following headers: id and email. The id corresponds to the Atlassian Account ID of the account you wish to modify. If you're unsure how to find the Atlassian Account IDs, please see the 'How do I retrieve Atlassian Account IDs from Atlassian Accounts?' section under FAQ.
  Additionally, ensure to include the new email address in the CSV file, under the email column. 

• Save it as a Bash Script: Name your file with the .sh extension (for example name_script.sh) and ensure it is saved in the same directory as your CSV file.

Once you have the above ready, open the terminal, navigate to the folder where the script is located and run it using the command ./name_script.sh. If you encounter any permission issues, consider using the chmod command to modify the permissions accordingly.

The example above illustrates a Bash script, but can also be adapted for Python, Java or PHP as per our documentation.

Identity Provider

When managing your users through an identity provider (IdP) such as Entra ID, Okta, or others, it is necessary to make changes directly within your IdP and allow those changes to sync with Atlassian. This synchronization can be achieved either through Just-in-Time Provisioning (SAML SSO) or regular User Provisioning (SCIM). Both methods require your Organization to have Atlassian Guard.

Just-in-Time Provisioning

Also referred to as JIT provisioning, this process enables user updates via SAML Single Sign-On (SSO). When a user authenticates through an Identity Provider (IdP) and is redirected to Atlassian, a SAML attribute known as NameID is included in the SAML Response. This attribute determines the email address associated with the logged-in Atlassian account, and by changing its value it will push an update on Atlassian’s end next time the user logs in.

To successfully update an email address through Just-In-Time (JIT) provisioning, it is essential that the Atlassian Account has been authenticated via Single Sign-On (SSO) at least once. This initial successful authentication establishes a SAML link, which is necessary for account/attribute updates, such as changes to email addresses.

In simpler terms, JIT provisioning for email changes can only be utilized for users who have previously authenticated through SSO via your Identity Provider (IdP).

If you try to perform this action for users who have not authenticated through SSO before, it will result in the creation of a new (duplicate) account associated with the new email domain.

To change an email address through JIT Provisioning, follow these steps:

1. Update the user's profile (NameID) on your identity provider to ensure the email reflects the new address.

2. Instruct the user to open an incognito tab and visit id.atlassian.com. While using incognito mode is optional, it is recommended for a fresh session.

3. Ask the user to enter their current (not new) email address on the Atlassian login screen and click 'Continue'.

4. The user will be redirected to your identity provider, where they must log in using their credentials.

5. After successful authentication, the user will be redirected back to Atlassian, and their email address should now reflect the new domain.

User Provisioning

Another approach of updating your Managed Accounts is through your identity provider with User Provisioning, also referred to as SCIM. By utilizing SCIM, you can actively synchronize users from your Identity Provider to Atlassian, enabling you to manage their product access through one or more synced groups. Additionally, this method allows you to synchronize specific attributes, including name, department, location, email address, and more.

To ensure users are updated through SCIM, they must already be synced before making any changes to their email. This synchronization links their accounts in the SCIM database to their Atlassian Accounts. You can then update the email address on your identity provider, so the changes reflect on Atlassian after the next synchronization cycle.

It is important to review your SCIM attribute mapping configuration. Depending on its configuration, you might be referencing the user's email field, or, it could be linked to the User Principal Name.

Frequently Asked Questions (FAQ)

How do I check if all new email addresses are available, and how do I deal with such accounts?

To begin, ensure that the desired domain is verified within your Atlassian Organization, as outlined on the top of this page. After verification, you can export a list (CSV) of all Atlassian Accounts associated with the new domain:

1. Go to Atlassian Administration. Select your organization if you have more than one.

2. This step is different depending on your user management experience:
   - Original: Select Directory > Domains.
   - Centralized: Select Settings > Domains.

3. Select Claim accounts for a domain.

4. Select Export users. You’ll receive an email with a link to the CSV file.

Reviewing the accounts listed in the CSV file will help you identify any duplicates.

In case you identify an Atlassian Account with a desired email address, it’s important to free it up so it can be used by the user’s actual account. Let’s take a look at the below example:

Atlassian Account A	Atlassian Account B
user1@owlpostmail.com	user1@hogwartsmail.net

To update the email address for Atlassian Account A to hogwartsmail.net, it is important to note that the desired email is currently in use. As a result, the update cannot proceed, since each email address must be unique to a single Atlassian Account. Therefore, you will first need to update Atlassian Account B before you can make changes to Atlassian Account A.

Before moving forward, it is crucial for the Organization Admin to verify with the user which account they consider their 'main' account. There may be instances where a user is actively utilizing Atlassian Account B and does not need an email update for Account A.

If you are the Organization Admin and have both Atlassian Accounts claimed under your Organization, you have two options: you can either change Atlassian Account B to a valid, different email address, or you can assign it to a non-existing email address (for example by adding _duplicate as can be seen below).

Atlassian Account A	Atlassian Account B
user1@owlpostmail.com	user1_duplicate@hogwartsmail.net

Since the previous email address no longer exists, you can proceed to update Atlassian Account A to reflect its new domain:

Atlassian Account A	Atlassian Account B
user1@hogwartsmail.net	user1_duplicate@hogwartsmail.net

You have the option to deactivate or mark Atlassian Account B for deletion, which can help clean up your user base. Keep in mind that deactivating the account provides you with a rollback option, should you need it in the future.

How do I retrieve Atlassian Account IDs from Atlassian Accounts?

You can retrieve it by visiting admin.atlassian.com > Directory > Managed Accounts > Export accounts. This action will send a file to your email address containing all your managed accounts along with their respective IDs.

You must have the domain verified and accounts claimed to perform this action.

Will users lose access, history or privileges during or after the email change?

Changing email addresses will not result in the loss of product access, data, or privileges. However, the primary concern is the potential creation of duplicate accounts. If users log in with their new email, they may encounter a situation where they cannot find their products and content, as they could be accessing a completely new account.

If new (duplicate) accounts got created, please see the ‘How do I check if all new email addresses are available, and how do I deal with such accounts?’ section at the beginning of the FAQ for instructions on how to resolve this.

Is there an option to merge two Atlassian Accounts?

Not at this moment, although we are collecting interest for such feature on our public feature request.

Help! I’m stuck with migrating email domains, what do I do?

If you need assistance, simply contact Atlassian Customer Support! Our dedicated engineers are ready to guide you through the migration process. You can reach us at https://support.atlassian.com/contact/.