You must enable javascript in order to use the Slack API Documentation. You can do this in your browser settings.
Go to Slack

Further narrowing access to user email field

Published: Saturday, April 1, 2017
Updated: Wednesday, August 22, 2018
APIs

Accessing email addresses
The users:read.email OAuth scope is now required to access the email field in user objects returned by the users.list and users.info web API methods. users:read is no longer a sufficient scope for this data field. Learn more.

Back in November 2016, we introduced the users:read.email OAuth permission scope, allowing more explicit access to email addresses.

To help developers with the transition, we automatically grandfathered apps asking for users:read created before January 4th, 2017.

We'd like to complete this transition and remove this grandfathering entirely on August 21, 2018 October 16, 2018.

Apps created before January 4th, 2017 with user tokens granted only the users:read scope will no longer receive the email field in user objects.

If you want access to email addresses, you'll need the new OAuth permission scope, users:read.email. It provides an explicit, additive way to request access to team email addresses.

Additionally, the bot scope will no longer grant bot user tokens access to email addresses. Bot users must utilize a user token and the users:read.email scope instead.

Don't need access to email address but do need access to user data? users:read should be all you need.

What's changing?

On October 16, 2018, all Slack apps must request the users:read.email OAuth scope to access the email field in user objects returned by the users.list and users.info web API methods. users:read will no longer be a sufficient scope for this data field, even for apps that were previously grandfathered.

Additionally, bot user tokens will no longer be granted access to the email field and user tokens granted through the application installation flow must be used instead.

What isn't changing?

users:read is still required to use users.info and users.list. You must still request users:read in addition to users:read.email.

Additionally, the OAuth scope users.profile:read can also be used to obtain access to email addresses, as they are considered part of the user's profile obtained via users.profile.get.

Furthermore, Sign in with Slack continues to operate the same way it does today — email address is yielded for the current user signing in to your application via the identity.email scope.

How do I prepare?

Add the users:read.email scope when using the OAuth flow or Add to Slack.

Building an open source library or toolkit that uses email? Configure it to ask for users:read.email by default.

users:read and users:read.email must be requested together as a delightful pair within the same authorization attempt.

When is this happening?

Our new OAuth scope, users:read.email, has been available since November 2016. On August 21, 2018 October 16, 2018 we'll end grandfathering of apps created before January 4th, 2017.

If your app uses a "bot user" token to retrieve email address today, you must modify those requests to utilize a "user token" granted the users:read.email OAuth scope instead, which you receive as part of the OAuth installation process.

"Bot user" tokens beginning with xoxb- no longer have access the email field.

When is this happening?

Our new OAuth scope, users:read.email, has been available since November 2016. On August 21, 2018 October 16, 2018 we'll end grandfathering of apps and bot user tokens created before January 4th, 2017.

As always, please contact us if you have any questions or concerns.

Review other recent updates