Go to Slack

Further narrowing access to user email field

Updated: 2017-08-02 APIs

Temporary rollback: We've reinstated access to the email attribute for bot and user tokens. On August 1, 2017 we proceeded with limiting email access to user tokens with users:read.email, originally announced in November 2016 and again, with a revised plan in April 2017.

We unfortunately took some developers by surprise after we waited until August 1st to finally roll out a change expected in July. We heard you, and will use ways to more directly notify you of changes like this before setting a new retirement date.

For now, it's business as usual for user and bot user tokens. Thanks to all the developers who were prepared and our sincere apologies to those who were not.

Subscribing to our new changelog rss feed using /feed in Slack is a great way to be notified of changes like this in the future.

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 July 5th, 2017.

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 July 5th, 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 July 5th, 2017 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 July 5th, 2017 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