Getting started with shared email

Shared email is an opt-in feature that lets you keep separate customer profiles for people who use the same email address. Two members of a household can share an inbox while each has their own Zendesk user id, profile, and ticket history.

This tutorial creates two users who share an address, then searches for both. It also explains how Zendesk selects a user when a workflow starts with an email address.

Basics

An email address on a user is a user identity, with type set to "email" and value set to the address. Its ownership property describes how that user holds the address:

Ownership	Meaning
owned	The user owns the address for identity lookup purposes. There can be at most one owner within the applicable account or brand scope.
shared	The user holds the address as a contact method. Several users can hold the same address as shared, with or without an owner.

Ownership is separate from being primary or verified. A shared email can be primary, and each holder’s verification state is independent. Verifying one identity does not verify the others. The user’s email property continues to contain the outbound email address.

Before you start, you need:

• An account where the shared email creation setting is enabled in Admin Center.
• An agent or admin credential with permission to create users.

Note: Only end users can hold shared email identities. Team members must always hold owned addresses.

Try it out

Casey and Jamie Rivera share a household inbox. Create Casey as the owner and Jamie as a shared holder, using a different external_id for each person.

Replace {subdomain} and {access_token} in the curl commands with your Zendesk subdomain and access token. All example data, including response ids, is fictitious. The example.com address illustrates identity matching; it cannot be used to test email delivery.

Step 1 - Create the owner

Use Create User with a nested email identity:

curl 'https://{subdomain}.zendesk.com/api/v2/users.json' \
  --request POST \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "name": "Casey Rivera",
      "role": "end-user",
      "identities": [
        {
          "type": "email",
          "value": "[email protected]",
          "primary": true,
          "ownership": "owned"
        }
      ]
    }
  }'

On success, the API returns 201 Created with Casey’s user record. Save its id; this example uses 101.

Step 2 - Create a separate user with the shared email

Give Jamie a different external id and explicitly set the identity to shared:

curl 'https://{subdomain}.zendesk.com/api/v2/users.json' \
  --request POST \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "name": "Jamie Rivera",
      "role": "end-user",
      "identities": [
        {
          "type": "email",
          "value": "[email protected]",
          "primary": true,
          "ownership": "shared"
        }
      ]
    }
  }'

The API returns 201 Created with Jamie’s separate user record. This example uses id 202.

Step 3 - Search for both users and inspect ownership

Use Search Users with the email query and sideload identities:

curl --get 'https://{subdomain}.zendesk.com/api/v2/users/search.json' \
  --header 'Authorization: Bearer {access_token}' \
  --data-urlencode 'query=email:[email protected]' \
  --data-urlencode 'include=identities'

A response can contain both users and their identities. Other properties are omitted here, and the order is illustrative:

{
  "users": [
    {
      "id": 101,
      "name": "Casey Rivera",
      "email": "[email protected]"
    },
    {
      "id": 202,
      "name": "Jamie Rivera",
      "email": "[email protected]"
    }
  ],
  "identities": [
    {
      "id": 77938,
      "user_id": 101,
      "type": "email",
      "value": "[email protected]",
      "primary": true,
      "ownership": "owned"
    },
    {
      "id": 77939,
      "user_id": 202,
      "type": "email",
      "value": "[email protected]",
      "primary": true,
      "ownership": "shared"
    }
  ]
}

The user_id on each identity links it to a user: Casey owns the address and Jamie holds it as shared. Both users have the same email, so that property alone cannot tell you who owns it.

Use the returned user ids, or your own external ids for subsequent calls that need to target a particular person.

Changing ownership

To make Jamie the owner, update Jamie’s existing shared identity with "ownership": "owned" using Update Identity. Zendesk will atomically update both identities in a single request: Jamie’s identity becomes owned, and Casey’s identity becomes shared.

How it works

Creating and reading identities

The tutorial uses the existing Users API to create each person with a nested email identity. The first request sets ownership to "owned"; the second sets it to "shared". These remain separate identity records on separate users. A single user cannot hold the same address as both owned and shared.

If you omit ownership when creating an email identity, it defaults to owned. Creating another owned identity for an address that already has an owner fails validation. To accept either outcome, use "auto_ownership": true on the identity instead of an explicit ownership value. With this set, Zendesk tries owned first and falls back to shared if another user owns the address.

Email identity responses include ownership for agent and admin callers, whether the callers fetch them directly using the User Identities API or sideload them. That is why the search request includes include=identities. Without it, the response would contain users without their identity objects.

Selecting one user from a shared address

When a workflow needs to select one user from an email address that multiple people hold, identity resolution is used to select one user. Because identity resolution can't always determine who sent a message from a shared inbox, an agent or API integration may need to correct the requester.

Workflow	How Zendesk selects the user
Native email/password sign-in and password reset	Uses the owned identity only. Shared identities cannot be used as credentials for these flows.
New tickets received by email	Uses the verified owner, then the oldest verified shared identity, then the unverified owner, then the oldest unverified shared identity. If no holder exists, creates a user with an owned identity.
Email-based CC resolution and suspended ticket recovery	Uses the same matching order as new inbound email.
Replies to an existing ticket	Uses the ticket’s participants first, preferring a matching requester and then an email CC, before falling back to email matching.
Requests from a signed-in Help Center user	Uses the signed-in user as requester, including when their email is shared.
SAML/JWT SSO with external_id	Matches external id first. A new external id can create a distinct user with a shared email when someone else owns the address.
Matching Messaging users	Matches external id first. If no match is found, a verified email can match an existing user with no external id, which is then assigned the external id.

“Oldest” refers to when the email identity was created. In integrations, use a Zendesk user id or a unique external_id to identify a particular person rather than relying on their email address.

Profiles, tickets, and notifications

Sharing an address does not merge user profiles or grant access to another holder’s requests in Help Center. Requester and CC access remains tied to individual user records; configured organization access still applies. People with access to the shared inbox can read messages delivered there.

A shared primary address can receive ticket notifications, subject to normal delivery rules. Shared email does not change notifications to use whichever secondary address originated a ticket.

Frequently asked questions

What changes if I leave shared email creation turned off?

Existing identities remain owned and behavior is unchanged. Agent and admin callers can still read the ownership property.

What happens if I turn shared email creation off later?

Existing shared identities keep working, and you can still change them to owned. New shared identity creation is blocked.

How do multiple users sign in when they share the same address?

Native email/password sign-in and password reset use the owned identity for that address. A shared identity cannot be used for those flows, even if it is verified.

Other holders can sign in using another email they own, or through SSO configured with a unique external_id for each person.

How is a ticket requester set when their email is held by multiple users?

For a new ticket received by email, Zendesk selects the first available match in this order: the verified owner, the oldest verified shared identity, the unverified owner, then the oldest unverified shared identity. "Oldest" refers to when the email identity was created.

For replies to an existing ticket, Zendesk first identifies the sender among existing participants holding that address, preferring the requester, then an email CC, before falling back to the same order.

What happens when users with the same email are merged?

The surviving user keeps one identity for the address.

Can JWT claims specify ownership?

No. JWT claims cannot specify ownership or auto_ownership.

Does Messaging always create a user when the external id is new?

No. A verified email can match an existing user with no external id.

Can users who share an address see each other's tickets?

Sharing an address does not itself grant Help Center access to another user's tickets. Access to the shared inbox itself is a separate consideration.

Where are ticket notifications sent?

A shared primary email can receive notifications under normal delivery rules.

What will agents and end users see?

Agents can identify shared emails in the UI and using the API. End users see email contact methods without ownership labels.