Send invitations
POST https://glommio.zulipchat.com/api/v1/invites
Send invitations to specified email addresses.
Changes: In Zulip 6.0 (feature level 126), the invite_expires_in_days
parameter was removed and replaced by invite_expires_in_minutes.
In Zulip 5.0 (feature level 117), added support for passing null as
the invite_expires_in_days parameter to request an invitation that never
expires.
In Zulip 5.0 (feature level 96), the invite_expires_in_days parameter was
added which specified the number of days before the invitation would expire.
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# Send invitations
request = {
"invitee_emails": "example@zulip.com, logan@zulip.com",
"invite_expires_in_minutes": 60 * 24 * 10, # 10 days
"invite_as": 400,
"stream_ids": [1, 8, 9],
}
result = client.call_endpoint(url="/invites", method="POST", request=request)
print(result)
curl -sSX POST https://glommio.zulipchat.com/api/v1/invites \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'invitee_emails=example@zulip.com, logan@zulip.com' \
--data-urlencode invite_expires_in_minutes=14400 \
--data-urlencode invite_as=600 \
--data-urlencode 'stream_ids=[1, 2]'
Parameters
invitee_emails string required
Example: "example@zulip.com, logan@zulip.com"
The string containing the email addresses, separated by commas or
newlines, that will be sent an invitation.
invite_expires_in_minutes integer | null optional
Example: 14400
The number of minutes before the invitation will expire. If null, the
invitation will never expire. If unspecified, the server will use a default
value (based on the INVITATION_LINK_VALIDITY_MINUTES server setting, which
defaults to 14400, i.e. 10 days) for when the invitation will expire.
Changes: New in Zulip 6.0 (feature level 126). Previously, there was an
invite_expires_in_days parameter, which specified the duration in days instead
of minutes.
invite_as integer optional
Example: 600
The organization-level role of the user that is
created when the invitation is accepted.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
Users can only create invitation links for
roles with equal or stricter restrictions
as their own. For example, a moderator cannot invite someone to be an owner
or administrator, but they can invite them to be a moderator or member.
Changes: In Zulip 4.0 (feature level 61), added support for inviting
users as moderators.
Must be one of: 100, 200, 300, 400, 600.
Defaults to 400.
stream_ids (integer)[] required
Example: [1, 2]
A list containing the IDs of the streams that the
newly created user will be automatically subscribed to if the invitation
is accepted. If the list is empty, then the new user will not be
subscribed to any streams.
Changes: Before Zulip 7.0 (feature level 180), specifying stream_ids
as an empty list resulted in an error.
Response
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"
}
An example JSON error response for when some of the specified email addresses
have existing Zulip accounts.
{
"code": "INVITATION_FAILED",
"daily_limit_reached": false,
"errors": [
[
"hamlet@zulip.com",
"Already has an account.",
false
]
],
"license_limit_reached": false,
"msg": "Some of those addresses are already using Zulip, so we didn't send them an invitation. We did send invitations to everyone else!",
"result": "error",
"sent_invitations": true
}
An example JSON error response for when the user doesn't have permission
to send invitations.
{
"code": "BAD_REQUEST",
"msg": "Insufficient permission",
"result": "error"
}
An example JSON error response for when no email address is specified.
{
"code": "BAD_REQUEST",
"msg": "You must specify at least one email address.",
"result": "error"
}
An example JSON error response for when any of the specified streams
does not exist or the user does not have permission to access one of
the targeted streams.
{
"code": "BAD_REQUEST",
"msg": "Stream does not exist with id: 11. No invites were sent.",
"result": "error"
}
An example JSON error response for when the user doesn't have permission
to subscribe other users to streams and stream_ids is not empty.
{
"code": "BAD_REQUEST",
"msg": "You do not have permission to subscribe other users to streams.",
"result": "error"
}