Guidelines for requesting access to email address

Email address is a user profile field managed by Atlassian Account. By default this field will be hidden from our public cloud REST APIs and no longer generally accessible to apps.

Apps may receive access to email address in the following ways:

  1. Individuals have unhidden their email address from public.
  2. Apps have received explicit consent from individuals through a 3LO consent flow.
  3. Apps using admin installation and consent flows (i.e. an admin has installed and consented on behalf of end users) have been approved to access the email API.

Keep in mind, the access to email address offered under #s 1 and 2 above can change based on user action. Individuals may choose to hide their email address at any time by changing their profile visibility settings. They may also choose to revoke consent previously given to an app to access to their personal account details via a 3LO flow. By contrast, apps using the Email API will have access to email address for all users across an instance as long as the app is actively installed. This access will not be affected by user opt-outs or changes in profile visibility settings.

The Email API is a public API (it will be documented like any other API we provide and officially supported by Atlassian), however only apps that have been approved and whitelisted will be able to use the API to retrieve email addresses.

In order to apply for access to this API the app must meet all current requirements for being listed on Atlassian Marketplace (even if the app is not listed on Atlassian Marketplace).

This means:

  • The app developer has provided a privacy policy
  • The app developer has provided a customer terms of use agreement
  • The app developer must signal whether or not the app collects and stores personal data.

If the app is storing personal data the app must report the accountIDs that have been collected and stored every 15 days. Read more on the personal data reporting API.

How to request access to the Email API

If you would like to request access, raise a ticket with our Developer Support team.

In your request you must provide:

  • Company name
  • App name
  • App ID (aka app key or add-on key)
  • Link to your app listing on Atlassian Marketplace OR URL to your privacy policy, customer terms of use, and an indication of whether or not your app stores personal data.
  • A description of the functionality provided by the app which requires email address (aka your use case).
  • The language from your privacy policy which describes how you process email address

Valid Use Cases

The following use cases will be considered for approval:

How email address is processed Functionality provided
Send transactional emails Send error reports
Send security alerts
Allow users to subscribe to alerts / news feeds
Allow users to invite other users to collaborate
Account Linking Connect a mail service for inbound / outbound mail processing
Sync users with another system

You may select multiple use cases. If one of the use cases you’d like to get approved is not in the above list, please include details about your use case in your ticket.

Use cases which will not be approved
How email address is processed Use Case
Send transactional emails Inviting users to company events
Send newsletters, campaigns, or other marketing emails
Send materials to facilitate end user onboarding
Send subscription / renewal reminders

The approval process:

Certain use cases are auto-approved pending completion of the request form. Other use cases will need to be reviewed further. Upon approval, we will notify you that you’ve been added to a whitelist and can begin using the Email API to receive email addresses for your approved use case.

We will also update your app listing on Atlassian Marketplace to inform our customers that your app has been approved to access email address despite profile visibility control settings. Upon install, your app will display a new scope associated with this API.

On appropriate use of the Email API

If you are using the Email API to receive access to email address you should only be using it to provide the functionality described in your request. Should you decide to build additional features / functionality which require email address you will need to update us by either raising a new request or updating your existing request.

You may not use email address in the UI. Email address is hidden by default which means displaying email address in the UI could leak private personal data to other users in that system.

Additionally, you may not share email addresses with any other third parties (including other apps) unless required to provide the service to the end user.

By accessing the Email API you also agree to our Atlassian Developer Terms andAtlassian Marketplace Vendor Agreement, which reserves Atlassian the right to conduct audits at any time to confirm your compliance with these Guidelines and any related procedures. We also reserve the right to remove your app at any time from the Email API whitelist which will prevent your app from receiving further access to email address, and if necessary, to de-list your app from Atlassian Marketplace.

7 Likes

Thank you for providing these guidelines. They are very helpful in supporting product planning on our end. FYI, the link to https://ecosystem.atlassian.net/servicedesk/customer/portal/14/create/284 is not working at this time.

Oops! please try again @boris (I hide it while I was setting up / testing).

1 Like

Confirmed working. Extra characters to pass the filter.

2 Likes

Thank you for providing us with a way to apply for the API access, Alexandra!

I have a question regarding the following.

Historically this type of emails helped us to improve user experience with our apps.

Is it possible to expand on this? I truly believe that our users are actually receiving ton of value from a properly designed “Tips & Tricks” email sequence.

@vit - Rather than emailing end users for onboarding, we’d recommend using the ‘get started’ / ‘configuration’ page onboarding pattern. To do this, create a postInstallPage to provide next steps about your app to the admin. Read the postInstallPage docs. This page is largely seen by admins so in order to get broader access to end users I’d recommend providing a template and instructions to get the admin involved or using in product notification patters like in product help and spotlight.

Our intention is to eliminate surprise where end users (who were not involved in the app install process) get emails from apps that have been installed in products where they participate. Overall, we’re trying to reduce the amount of emails and restrict its use to provide product functionality.

2 Likes

@akassab is there any thought of adding an API that allows addons to send notifications to users without needing access to their email address?

The use case we have is that we would like to notify users when certain things happen in our addon, similar to how Jira and Confluence send out notifications.
Ideally, we would like to avoid needing access to the email address, and instead simply invoke an API on the Atlassian side that says “go notify this user of X”.
This would reduce the need for us (and potentially other vendors too) to even need the email address, and such functionality could tie to the built-in notification settings, thus providing end-users with even greater control over what they receive.

9 Likes

@ademoss - Actually yes, there was some talk of a notification service - I think I mentioned it during App Week Amsterdam 2018. We decided to go this route first for two reasons: enabling account linking use cases (e.g. connect Jira to Outlook, etc.) and the second is that Jira and Confluence are in the process of revamping their notification systems which we believe needs to be built first. This topic is still on our backlog though.

@akassab
I have a question regarding the quoted text below I read in the new vendor agreement:

© End User Communication. You may use End User Data to communicate directly with end users, provided that such communication is: (i) with technical and billing contacts, (ii) required under applicable law, or (iii) consented to or requested by the end user. In all cases, you will ensure that any communication with end users is conducted in accordance with all applicable laws (including obtaining all required end user consents). Notwithstanding the foregoing, you shall not send marketing messages to end users within any product experience integrated with Atlassian products without the explicit written consent of Atlassian.

Would this imply that we always have access to the email of the technical/billing contact in lifecycle calls or through the API in order to communicate directly with these end users?

1 Like

@f.demir - No. We have separate mechanisms for each.

To get contact information for Billing and Technical contacts you can use the Sales Report API (separate from product APIs) provided through Atlassian Marketplace.

To get access to end user emails you can either build a 3LO app in which you would gain consent from the end user on install or you could request access to the Email API described on this page.

2 Likes

If I’m developing an application on a Cloud instance for internal-use by employees (i.e. not distributed on the marketplace), will I still need to submit a request for an exception? The company is globally distributed, but the application is not using the data for anything other than linking user profiles.

Hi @david.gunter - yes. We need to add your app to an internal whitelist. Otherwise the API will not work.

@akassab - I see in the weekly update that the Email API is ready.

Can you point me/us to the documentation for that API?

Here I believe:
https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-user-email-get

1 Like

This is fine for ID to email address. What about the other way around? Say you have been given an email address - how would you query Jira to get an account ID for that address (if one exists)?

@akassab,

How, in the context of GDPR and the Email API, the following REST endpoint works: https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-issue-issueIdOrKey-notify-post

  • Does it still work? Can we still use it?
  • It used to accept usernames (at least example suggests it). Has it been changed to accept Atlassian account ID?

It is either not GDPR ready or documentation was not updated.

Another question: are there any plans to let apps post notifications to the new Jira notification area? Is there any issue that we can watch and vote? I wasn’t able to find any. Our customers ask for that.

Thanks,
Jack

1 Like

Is access to the Email API available restricted to Apps, or could requests outside an App also be given access? Also, is there public documentation on the whitelisting mechanism?

Cheers

@MichaelNelson - The restricted email API is only available to apps. Direct REST calls or functionality provided through scripts, etc. using API tokens are not. The whitelisting mechanism is and will not be documented. The process for getting whitelisted is covered above and also available here: https://developer.atlassian.com/cloud/jira/platform/profile-visibility/

Thank you for clarifying this, Alexandra.

Cheers

@akassab I have a request open since 25th of July, could someone finally take a look - https://ecosystem.atlassian.net/servicedesk/customer/portal/14/DEVHELP-3190