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.
This original plan has been updated. Grandfathering is no longer in effect. Please see this post from April 2017 for more information.
We've added a new OAuth permission scope called users:read.email and it provides a new explicit, additive way to request access to team email addresses. If you don't need email addresses but do need other user info, users:read is still all you need.
Apps created before January 4th, 2017 are grandfathered and will continue behaving in a backwards-compatible way. Apps created after that date must request the new users:read.email scope. Regardless of creation date, we encourage all apps to migrate to this new scope.
Slack apps created after the cut off date must request the new 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.
If you have code you plan to re-use in a new application record and that code only asks for users:read, you won't find email addresses in these methods.
You'll need to request both users:read and users:read.email while installing the app.
users:read is still required to use users.info and users.list.
We're grandfathering existing Slack apps so these methods will continue including email when you've only requested or are requesting users:read.
Your vintage scope retains its data-inclusive approach. You've already requested and earned that permission.
That said, we encourage you to use the new scopes anyway!
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.
If you're building an application consuming the email field in 2017 and beyond, you'll need to 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.
Regardless of when your app was created, if email addresses are important for your app, we strongly recommend you also request users:read.email as team members install your app.
For non-grandfathered apps, you must request users:read.email to enable the email field to appear in user objects presented in methods like users.info and users.list.
Our new OAuth scope, users:read.email, is available now.
Apps created after January 4th, 2017 will need to request this scope to receive the email addresses in these Web API methods. Apps from yesteryear will do as they've always done.
As always, please contact us if you have any questions or concerns.