Why does /api/v2/users-by-email endpoint return a list?

The api documentation describes the users-by-email endpoint with the following:
" The GET /api/v2/users-by-email endpoint allows you to search for users using their email addresses."

The example on the same page shows the response as a list. Email is described as a natural key elsewhere in the documentation though. And other topics that I’ve read have answers saying that two users cannot exist with the same email.

Why does this endpoint return a list? When would it be possible to have two users with the same email address?

Hey there @pandomg welcome to the community!

Technically, 2 users with the same email can exist in separate connections. That’s really the only scenario I can think of where this is possible.

Hope this helps!

If I had an email duplicated across multiple connections, would they both be returned by this endpoint?

How would I tell which user in the list is from which connection?

I see a connection field on the the identities, but that is a list on a user, which implies to me that that a single user could have multiple connections.

That’s correct.

If you had 2 users with the same email, this endpoint would return both user profiles - Each profile will contain its own Identities array with the connection, provider, user_id, etc.

If account linking is enabled then a single user could be associated with multiple connections.