Send invitations

POST https://yourZulipDomain.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, 11, 12],
}
result = client.call_endpoint(url="/invites", method="POST", request=request)
print(result)

curl -sSX POST https://yourZulipDomain.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, 10]' \
    --data-urlencode include_realm_default_subscriptions=false

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, 10]

A list containing the IDs of the channels that the newly created user will be automatically subscribed to if the invitation is accepted, in addition to any default channels that the new user may be subscribed to based on the include_realm_default_subscriptions parameter.

This list must be empty if the current user has the unlikely configuration of being able to send invitations while lacking permission to subscribe other users to channels.

Changes: Before Zulip 7.0 (feature level 180), specifying stream_ids as an empty list resulted in an error.


include_realm_default_subscriptions boolean optional

Example: false

Boolean indicating whether the newly created user should be subscribed to the default channels for the organization.

Note that this parameter can be true even if the user creating the invitation does not generally have permission to subscribe other users to channels.

Changes: New in Zulip 9.0 (feature level 261). Previous versions of Zulip behaved as though this parameter was always false; clients needed to include the organization's default channels in the stream_ids parameter for a newly created user to be automatically subscribed to them.

Defaults to false.


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 channels does not exist or the user does not have permission to access one of the targeted channels.

{
    "code": "BAD_REQUEST",
    "msg": "Invalid channel 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 channels and stream_ids is not empty.

{
    "code": "BAD_REQUEST",
    "msg": "You do not have permission to subscribe other users to channels.",
    "result": "error"
}