Get a user by email
GET https://mathematical-logic.zulipchat.com/api/v1/users/{email}
Fetch details for a single user in the organization given a Zulip
API email address.
You can also fetch details on all users in the organization
or by user ID.
Fetching by user ID is generally recommended when possible,
as a user might change their email address
or change their email address visibility,
either of which could change the client's ability to look them up by that
email address.
Changes: Starting with Zulip 10.0 (feature level 302), the real email
address can be used in the email
parameter and will fetch the target user's
data if and only if the target's email visibility setting permits the requester
to see the email address.
The dummy email addresses of the form user{id}@{realm.host}
still work, and
will now work for all users, via identifying them by the embedded user ID.
New in Zulip Server 4.0 (feature level 39).
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
result = client.call_endpoint(
url=f"/users/{email}",
method="GET",
)
print(result)
curl -sSX GET -G https://mathematical-logic.zulipchat.com/api/v1/users/iago@zulip.com \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY
You may pass the client_gravatar
or include_custom_profile_fields
query parameter as follows:
curl -sSX GET -G https://mathematical-logic.zulipchat.com/api/v1/users/iago@zulip.com \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode client_gravatar=false \
--data-urlencode include_custom_profile_fields=true
Parameters
email string required in path
Example: "iago@zulip.com"
The email address of the user to fetch. Two forms are supported:
-
The real email address of the user (delivery_email
). The lookup will
succeed if and only if the user exists and their email address visibility
setting permits the client to see the email address.
-
The dummy Zulip API email address of the form user{user_id}@{realm_host}
. This
is identical to simply getting user by ID. If the server or
realm change domains, the dummy email address used has to be adjustment to
match the new realm domain. This is legacy behavior for
backwards-compatibility, and will be removed in a future release.
Changes: Starting with Zulip 10.0 (feature level 302), lookups by real email
address match the semantics of the target's email visibility setting and dummy
email addresses work for all users, independently of their email visibility
setting.
Previously, lookups were done only using the Zulip API email addresses.
client_gravatar boolean optional
Example: false
Whether the client supports computing gravatars URLs. If
enabled, avatar_url
will be included in the response only
if there is a Zulip avatar, and will be null
for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The client_gravatar
field is set to true
if
clients can compute their own gravatars.
Changes: The default value of this parameter was false
prior to Zulip 5.0 (feature level 92).
Defaults to true
.
include_custom_profile_fields boolean optional
Example: true
Whether the client wants custom profile field
data to be included in the response.
Changes: New in Zulip 2.1.0. Previous versions do not offer these
data via the API.
Defaults to false
.
Response
Return values
-
user
: object
A dictionary containing basic data on a given Zulip user.
Changes: Removed is_billing_admin
field in Zulip 10.0 (feature level 363), as it was
replaced by the can_manage_billing_group
realm setting.
-
user_id
: integer
The unique ID of the user.
-
delivery_email
: string | null
The user's real email address. This value will be null
if you cannot
access user's real email address. For bot users, this field is always
set to the real email of the bot, because bot users always have
email_address_visibility
set to everyone.
Changes: Prior to Zulip 7.0 (feature level 163), this field was
present only when email_address_visibility
was restricted and you had
access to the user's real email. As of this feature level, this field
is always present, including the case when email_address_visibility
is set to everyone (and therefore not restricted).
-
email
: string
The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
-
full_name
: string
Full name of the user or bot, used for all display purposes.
-
date_joined
: string
The time the user account was created.
-
is_active
: boolean
A boolean specifying whether the user account has been deactivated.
-
is_owner
: boolean
A boolean specifying whether the user is an organization owner.
If true, is_admin
will also be true.
Changes: New in Zulip 3.0 (feature level 8).
-
is_admin
: boolean
A boolean specifying whether the user is an organization administrator.
-
is_guest
: boolean
A boolean specifying whether the user is a guest user.
-
is_bot
: boolean
A boolean specifying whether the user is a bot or full account.
-
bot_type
: integer | null
An integer describing the type of bot:
null
if the user isn't a bot.
1
for a Generic
bot.
2
for an Incoming webhook
bot.
3
for an Outgoing webhook
bot.
4
for an Embedded
bot.
-
bot_owner_id
: integer | null
If the user is a bot (i.e. is_bot
is true), then bot_owner_id
is the user ID of the bot's owner (usually, whoever created the bot).
Will be null
for legacy bots that do not have an owner.
Changes: New in Zulip 3.0 (feature level 1). In previous
versions, there was a bot_owner
field containing the email
address of the bot's owner.
-
role
: integer
Organization-level role of the user.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
Changes: New in Zulip 4.0 (feature level 59).
-
timezone
: string
The IANA identifier of the user's profile time zone,
which is used primarily to display the user's local time to other users.
-
avatar_url
: string | null
URL for the user's avatar.
Will be null
if the client_gravatar
query parameter was set to true
, the current user has access to
this user's real email address, and this user's avatar is hosted by
the Gravatar provider (i.e. this user has never uploaded an avatar).
Changes: Before Zulip 7.0 (feature level 163), access to a
user's real email address was a realm-level setting. As of this
feature level, email_address_visibility
is a user setting.
In Zulip 3.0 (feature level 18), if the client has the
user_avatar_url_field_optional
capability, this will be missing at
the server's sole discretion.
-
avatar_version
: integer
Version for the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with ?v={avatar_version}
.
-
profile_data
: object
Only present if is_bot
is false; bots can't have custom profile fields.
A dictionary containing custom profile field data for the user. Each entry
maps the integer ID of a custom profile field in the organization to a
dictionary containing the user's data for that field. Generally the data
includes just a single value
key; for those custom profile fields
supporting Markdown, a rendered_value
key will also be present.
Example response(s)
Changes: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported
array.
A typical successful JSON response may look like:
{
"msg": "",
"result": "success",
"user": {
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"bot_type": null,
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"delivery_email": null,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet",
"is_active": true,
"is_admin": false,
"is_bot": false,
"is_guest": false,
"is_owner": false,
"profile_data": {
"1": {
"rendered_value": "<p>+0-11-23-456-7890</p>",
"value": "+0-11-23-456-7890"
},
"2": {
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius"
},
"3": {
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate"
},
"4": {
"value": "0"
},
"5": {
"value": "1900-01-01"
},
"6": {
"value": "https://blog.zulig.org"
},
"7": {
"value": "[11]"
},
"8": {
"value": "zulipbot"
}
},
"role": 400,
"timezone": "",
"user_id": 10
}
}