If Office originally came pre-installed and you need to reinstall on it on the same device or a new device, you should already have a Microsoft account associated with your copy of Office. This is the account you'll use to install Office following the steps below.
The Open Office 2019 Premium 2 Disc Set gives you the capabilities of Microsoft Office + more for a fraction of the cost! This '4 for 1' bundle is the #1 best alternative to those expensive office suites. Details Disc 1: Open Office Software Suite covers all the needs for Work, Students, Businesses, or Home users on PC or Mac. Common information about registering and getting authorization, supported versions of endpoints, target users, and using the client library to access user mailbox for all Outlook REST API, including mail, calendar, contacts, people, data extensions, extended properties, notifications, and user photo.
-->The OAuth 2.0 authorization code grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. Using the Microsoft identity platform implementation of OAuth 2.0, you can add sign in and API access to your mobile and desktop apps.
This article describes how to program directly against the protocol in your application using any language. When possible, we recommend you use the supported Microsoft Authentication Libraries (MSAL) instead to acquire tokens and call secured web APIs. Also take a look at the sample apps that use MSAL.
The OAuth 2.0 authorization code flow is described in section 4.1 of the OAuth 2.0 specification. It's used to perform authentication and authorization in the majority of app types, including single page apps, web apps, and natively installed apps. The flow enables apps to securely acquire access_tokens that can be used to access resources secured by the Microsoft identity platform endpoint, as well as refresh tokens to get additional access_tokens, and ID tokens for the signed in user.
Protocol diagram
At a high level, the entire authentication flow for an application looks a bit like this:
Redirect URI setup required for single-page apps
The authorization code flow for single page applications requires some additional setup. Follow the instructions for creating your single-page application to correctly mark your redirect URI as enabled for CORS. To update an existing redirect URI to enable CORS, open the manifest editor and set the type
field for your redirect URI to spa
in the replyUrlsWithType
section. You can also click on the redirect URI in the 'Web' section of the Authentication tab, and select the URIs you want to migrate to using the authorization code flow.
The spa
redirect type is backwards compatible with the implicit flow. Apps currently using the implicit flow to get tokens can move to the spa
redirect URI type without issues and continue using the implicit flow.
If you attempt to use the authorization code flow and see this error:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Then you need to visit your app registration and update the redirect URI for your app to type spa
.
Request an authorization code
The authorization code flow begins with the client directing the user to the /authorize
endpoint. In this request, the client requests the openid
, offline_access
, and https://graph.microsoft.com/mail.read
permissions from the user. Some permissions are admin-restricted, for example writing data to an organization's directory by using Directory.ReadWrite.All
. If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions. To request access to admin-restricted scopes, you should request them directly from a company administrator. For more information, read Admin-restricted permissions.
Tip https://heisixdicu1970.mystrikingly.com/blog/mac-os-catalina-review.
Click the link below to execute this request! After signing in, your browser should be redirected to https://localhost/myapp/
with a code
in the address bar.https://login.microsoftonline.com/common/oauth2/v2.0/authorize.
Parameter | Required/optional | Description |
---|---|---|
tenant | required | The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are common , organizations , consumers , and tenant identifiers. For more detail, see protocol basics. |
client_id | required | The Application (client) ID that the Azure portal – App registrations experience assigned to your app. |
response_type | required | Must include code for the authorization code flow. |
redirect_uri | required | The redirect_uri of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect_uris you registered in the portal, except it must be url encoded. For native & mobile apps, you should use the default value of https://login.microsoftonline.com/common/oauth2/nativeclient . |
scope | required | A space-separated list of scopes that you want the user to consent to. For the /authorize leg of the request, this can cover multiple resources, allowing your app to get consent for multiple web APIs you want to call. |
response_mode | recommended | Specifies the method that should be used to send the resulting token back to your app. Can be one of the following: - query - fragment - form_post query provides the code as a query string parameter on your redirect URI. If you're requesting an ID token using the implicit flow, you can't use query as specified in the OpenID spec. If you're requesting just the code, you can use query , fragment , or form_post . form_post executes a POST containing the code to your redirect URI. For more info, see OpenID Connect protocol. |
state | recommended | A value included in the request that will also be returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. The value can also encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on. |
prompt | optional | Indicates the type of user interaction that is required. The only valid values at this time are login , none , and consent .- prompt=login will force the user to enter their credentials on that request, negating single-sign on.- prompt=none is the opposite - it will ensure that the user isn't presented with any interactive prompt whatsoever. If the request can't be completed silently via single-sign on, the Microsoft identity platform endpoint will return an interaction_required error.- prompt=consent will trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.- prompt=select_account will interrupt single sign-on providing account selection experience listing all the accounts either in session or any remembered account or an option to choose to use a different account altogether. |
login_hint | optional | Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know their username ahead of time. Often apps will use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim. |
domain_hint | optional | If included, it will skip the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience - for example, sending them to their federated identity provider. Often apps will use this parameter during re-authentication, by extracting the tid from a previous sign-in. If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad , you should use domain_hint=consumers . Otherwise, use domain_hint=organizations . |
code_challenge | recommended / required | Used to secure authorization code grants via Proof Key for Code Exchange (PKCE). Required if code_challenge_method is included. For more information, see the PKCE RFC. This is now recommended for all application types - native apps, SPAs, and confidential clients like web apps. |
code_challenge_method | recommended / required | The method used to encode the code_verifier for the code_challenge parameter. This SHOULD be S256 , but the spec allows the use of plain if for some reason the client cannot support SHA256. If excluded, code_challenge is assumed to be plaintext if code_challenge is included. Microsoft identity platform supports both plain and S256 . For more information, see the PKCE RFC. This is required for single page apps using the authorization code flow. |
At this point, the user will be asked to enter their credentials and complete the authentication. The Microsoft identity platform endpoint will also ensure that the user has consented to the permissions indicated in the scope
query parameter. If the user has not consented to any of those permissions, it will ask the user to consent to the required permissions. Details of permissions, consent, and multi-tenant apps are provided here.
Once the user authenticates and grants consent, the Microsoft identity platform endpoint will return a response to your app at the indicated redirect_uri
, using the method specified in the response_mode
parameter.
Successful response
A successful response using response_mode=query
looks like:
Parameter | Description |
---|---|
code | The authorization_code that the app requested. The app can use the authorization code to request an access token for the target resource. Authorization_codes are short lived, typically they expire after about 10 minutes. |
state | If a state parameter is included in the request, the same value should appear in the response. The app should verify that the state values in the request and response are identical. |
You can also receive an access token and ID token if you request one and have the implicit grant enabled in your application registration. This is sometimes referred to as the 'hybrid flow', and is used by frameworks like ASP.NET.
Error response
Error responses may also be sent to the redirect_uri
so the app can handle them appropriately:
Parameter | Description |
---|---|
error | An error code string that can be used to classify types of errors that occur, and can be used to react to errors. |
error_description | A specific error message that can help a developer identify the root cause of an authentication error. |
Error codes for authorization endpoint errors
The following table describes the various error codes that can be returned in the error
parameter of the error response.
Error Code | Description | Client Action |
---|---|---|
invalid_request | Protocol error, such as a missing required parameter. | Fix and resubmit the request. This is a development error typically caught during initial testing. |
unauthorized_client | The client application isn't permitted to request an authorization code. | This error usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD. |
access_denied | Resource owner denied consent | The client application can notify the user that it can't proceed unless the user consents. |
unsupported_response_type | The authorization server does not support the response type in the request. | Fix and resubmit the request. This is a development error typically caught during initial testing. |
server_error | The server encountered an unexpected error. | Retry the request. These errors can result from temporary conditions. The client application might explain to the user that its response is delayed to a temporary error. |
temporarily_unavailable | The server is temporarily too busy to handle the request. | Retry the request. The client application might explain to the user that its response is delayed because of a temporary condition. |
invalid_resource | The target resource is invalid because it does not exist, Azure AD can't find it, or it's not correctly configured. | This error indicates the resource, if it exists, has not been configured in the tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD. |
login_required | Too many or no users found | The client requested silent authentication (prompt=none ), but a single user could not found. This may mean there are multiple users active in the session, or no users. This takes into account the tenant chosen (for example, if there are two Azure AD accounts active and one Microsoft account, and consumers is chosen, silent authentication will work). |
interaction_required | The request requires user interaction. | An additional authentication step or consent is required. Retry the request without prompt=none . |
Request an access token
Now that you've acquired an authorization_code and have been granted permission by the user, you can redeem the code
for an access_token
to the desired resource. Do this by sending a POST
request to the /token
endpoint:
Tip
Try executing this request in Postman! (Don't forget to replace the code
)
Parameter | Required/optional | Description |
---|---|---|
tenant | required | The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are common , organizations , consumers , and tenant identifiers. For more detail, see protocol basics. |
client_id | required | The Application (client) ID that the Azure portal – App registrations page assigned to your app. |
grant_type | required | Must be authorization_code for the authorization code flow. |
scope | optional | A space-separated list of scopes. The scopes must all be from a single resource, along with OIDC scopes (profile , openid , email ). For a more detailed explanation of scopes, refer to permissions, consent, and scopes. This is a Microsoft extension to the authorization code flow, intended to allow apps to declare the resource they want the token for during token redemption. |
code | required | The authorization_code that you acquired in the first leg of the flow. |
redirect_uri | required | The same redirect_uri value that was used to acquire the authorization_code. |
client_secret | required for confidential web apps | The application secret that you created in the app registration portal for your app. You shouldn't use the application secret in a native app or single page app because client_secrets can't be reliably stored on devices or web pages. It's required for web apps and web APIs, which have the ability to store the client_secret securely on the server side. The client secret must be URL-encoded before being sent. For more information on uri encoding, see the URI Generic Syntax specification. |
code_verifier | recommended | The same code_verifier that was used to obtain the authorization_code. Required if PKCE was used in the authorization code grant request. For more information, see the PKCE RFC. |
Successful response
A successful token response will look like:
Parameter | Description |
---|---|
access_token | The requested access token. The app can use this token to authenticate to the secured resource, such as a web API. |
token_type | Indicates the token type value. The only type that Azure AD supports is Bearer |
expires_in | How long the access token is valid (in seconds). |
scope | The scopes that the access_token is valid for. Optional - this is non-standard, and if omitted the token will be for the scopes requested on the initial leg of the flow. |
refresh_token | An OAuth 2.0 refresh token. The app can use this token acquire additional access tokens after the current access token expires. Refresh_tokens are long-lived, and can be used to retain access to resources for extended periods of time. For more detail on refreshing an access token, refer to the section below. Note: Only provided if offline_access scope was requested. |
id_token | A JSON Web Token (JWT). The app can decode the segments of this token to request information about the user who signed in. The app can cache the values and display them, and confidential clients can use this for authorization. For more information about id_tokens, see the id_token reference . Note: Only provided if openid scope was requested. |
Error response
Error responses will look like:
Parameter | Description |
---|---|
error | An error code string that can be used to classify types of errors that occur, and can be used to react to errors. |
error_description | A specific error message that can help a developer identify the root cause of an authentication error. |
error_codes | A list of STS-specific error codes that can help in diagnostics. |
timestamp | The time at which the error occurred. |
trace_id | A unique identifier for the request that can help in diagnostics. |
correlation_id | A unique identifier for the request that can help in diagnostics across components. |
Error codes for token endpoint errors
Error Code | Description | Client Action |
---|---|---|
invalid_request | Protocol error, such as a missing required parameter. | Fix the request or app registration and resubmit the request |
invalid_grant | The authorization code or PKCE code verifier is invalid or has expired. | Try a new request to the /authorize endpoint and verify that the code_verifier parameter was correct. |
unauthorized_client | The authenticated client isn't authorized to use this authorization grant type. | This usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD. |
invalid_client | Client authentication failed. | The client credentials aren't valid. To fix, the application administrator updates the credentials. |
unsupported_grant_type | The authorization server does not support the authorization grant type. | Change the grant type in the request. This type of error should occur only during development and be detected during initial testing. |
invalid_resource | The target resource is invalid because it does not exist, Azure AD can't find it, or it's not correctly configured. | This indicates the resource, if it exists, has not been configured in the tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD. |
interaction_required | Non-standard, as the OIDC specification calls for this only on the /authorize endpoint.The request requires user interaction. For example, an additional authentication step is required. | Retry the /authorize request with the same scopes. |
temporarily_unavailable | The server is temporarily too busy to handle the request. | Retry the request after a small delay. The client application might explain to the user that its response is delayed because of a temporary condition. |
consent_required | The request requires user consent. This error is non-standard, as it's usually only returned on the /authorize endpoint per OIDC specifications. Returned when a scope parameter was used on the code redemption flow that the client app does not have permission to request. | The client should send the user back to the /authorize endpoint with the correct scope in order to trigger consent. |
invalid_scope | The scope requested by the app is invalid. | Update the value of the scope parameter in the authentication request to a valid value. |
Note
Single page apps may receive an invalid_request
error indicating that cross-origin token redemption is permitted only for the 'Single-Page Application' client-type. This indicates that the redirect URI used to request the token has not been marked as a spa
redirect URI. Review the application registration steps on how to enable this flow.
Use the access token
Now that you've successfully acquired an access_token
, you can use the token in requests to web APIs by including it in the Authorization
header:
Tip
Execute this request in Postman! (Replace the Authorization
header first)
Refresh the access token
Access_tokens are short lived, and you must refresh them after they expire to continue accessing resources. You can do so by submitting another POST
request to the /token
endpoint, this time providing the refresh_token
instead of the code
. Refresh tokens are valid for all permissions that your client has already received consent for - thus, a refresh token issued on a request for scope=mail.read
can be used to request a new access token for scope=api://contoso.com/api/UseResource
.
Refresh tokens for web apps and native apps do not have specified lifetimes. Typically, the lifetimes of refresh tokens are relatively long. However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. Your application needs to expect and handle errors returned by the token issuance endpoint correctly. Single page apps, however, get a token with a 24 hour lifetime, requiring a new authentication every day. This can be done silently in an iframe when 3rd party cookies are enabled, but must be done in a top level frame (either full page navigation or a popup) in browsers without 3rd party cookies such as Safari.
Although refresh tokens aren't revoked when used to acquire new access tokens, you are expected to discard the old refresh token. The OAuth 2.0 spec says: 'The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client.'
Important
For refresh tokens sent to a redirect URI registered as spa
, the refresh token will expire after 24 hours. Additional refresh tokens acquired using the initial refresh token will carry over that expiration time, so apps must be prepared to re-run the authorization code flow using an interactive authentication to get a new refresh token every 24 hours. Users do not have to enter their credentials, and will usually not even see any UX, just a reload of your application - but the browser must visit the login page in a top level frame in order to see the login session. This is due to privacy features in browsers that block 3rd party cookies.
Tip
Try executing this request in Postman! (Don't forget to replace the refresh_token
)
Parameter | Type | Description |
---|---|---|
tenant | required | The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are common , organizations , consumers , and tenant identifiers. For more detail, see protocol basics. |
client_id | required | The Application (client) ID that the Azure portal – App registrations experience assigned to your app. |
grant_type | required | Must be refresh_token for this leg of the authorization code flow. |
scope | required | A space-separated list of scopes. The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the original authorization_code request leg. If the scopes specified in this request span multiple resource server, then the Microsoft identity platform endpoint will return a token for the resource specified in the first scope. For a more detailed explanation of scopes, refer to permissions, consent, and scopes. |
refresh_token | required | The refresh_token that you acquired in the second leg of the flow. |
client_secret | required for web apps | The application secret that you created in the app registration portal for your app. It should not be used in a native app, because client_secrets can't be reliably stored on devices. It's required for web apps and web APIs, which have the ability to store the client_secret securely on the server side. This secret needs to be URL-Encoded. For more information, see the URI Generic Syntax specification. |
Successful response
A successful token response will look like:
Parameter | Description |
---|---|
access_token | The requested access token. The app can use this token to authenticate to the secured resource, such as a web API. |
token_type | Indicates the token type value. The only type that Azure AD supports is Bearer |
expires_in | How long the access token is valid (in seconds). |
scope | The scopes that the access_token is valid for. |
refresh_token | A new OAuth 2.0 refresh token. You should replace the old refresh token with this newly acquired refresh token to ensure your refresh tokens remain valid for as long as possible. Note: Only provided if offline_access scope was requested. |
id_token | An unsigned JSON Web Token (JWT). The app can decode the segments of this token to request information about the user who signed in. The app can cache the values and display them, but it should not rely on them for any authorization or security boundaries. For more information about id_tokens, see the id_token reference . Note: Only provided if openid scope was requested. |
Error response
Parameter | Description |
---|---|
error | An error code string that can be used to classify types of errors that occur, and can be used to react to errors. |
error_description | A specific error message that can help a developer identify the root cause of an authentication error. |
error_codes | A list of STS-specific error codes that can help in diagnostics. |
timestamp | The time at which the error occurred. |
trace_id | A unique identifier for the request that can help in diagnostics. |
correlation_id | A unique identifier for the request that can help in diagnostics across components. |
For a description of the error codes and the recommended client action, see Error codes for token endpoint errors.
-->Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
Note
Use Microsoft Graph to build richer scenarios for Microsoft 365 servicesincluding Outlook. Find out how to transition to Microsoft Graph-based Outlook REST API.
The Outlook REST API includes the following subsets to allow access to users' mailbox data in Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.
The following table lists the first version that the core functionality of each subset was made available. Note that within a subset, new features and API can be subsequently added to a later version.
API subset | Available versions |
---|---|
Batching multiple API calls | v2.0, beta |
Calendar API | v2.0, v1.0, beta |
Contacts API | v2.0, v1.0, beta |
Data Extensions API | v2.0, beta |
Extended Properties API | v2.0, beta |
Mail API | v2.0, v1.0, beta |
Push Notifications API | v2.0, beta |
Streaming Notifications API (preview) | beta |
People API | beta |
Task API | v2.0, beta |
User Photo API | v2.0, beta |
Note
The rest of this article describes common information applicable to all subsets of the Outlook REST API. For simplicity of reference, the rest of this article uses Outlook.com to include accounts in the domains Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.
Register and authenticate your app
To use the Outlook REST API to access a user's mailbox data, your app should handle registration and user authorization:
First, register your app to get access to the Outlook REST API. You can then implement the API calls in your app.
At runtime, get authorization from the user and make REST API requests to access the user's mailbox.
There are currently two approaches to handle app registration and user authorization:
Azure AD v2 authentication endpoint
The Azure AD v2 authentication endpoint simplifies building an app that works with both Microsoft organizational andpersonal accounts. It enables work, school, and personal account users to sign in with a single button.
This converged programming model is the latest approach and is comprised of the following:
- v2 authentication endpoints
- v2 ADAL libraries
This approach gives you a seamless app registration and user authorization experience to get the appropriatetokens to access users' mailbox data on Office 365 and/or Outlook.com. If you are developing an app for Outlook.com,you must use this approach.
Instead of requesting permissions during app registration, the v2 authentication endpoint lets you dynamically promptand request the necessary permissions based on corresponding user actions at runtime.
This converged programming model consists of several components, so if you use one component, you should use the others as well.
To learn more, see examples on getting started,and Authenticate Office 365 and Outlook.com APIs using the the v2 authentication endpoint.
Important
As you create or update an app, make sure your app can handle Outlook.com mailboxes that havebeen enabled and you can access using the Outlook REST API, and those mailboxes that are waiting to be enabled. Find outmore about testing and handling such Outlook.com scenarios.
Register and authenticate using Azure AD and OAuth
This is an earlier approach to access mailbox data on only Office 365. If you're planning to access data on Outlook.com, or create a new app for Office 365, use the v2 authentication endpoint instead.
For the time being, to access Office 365 mailbox data, you can continue to register an app in Azure AD as before, specifying the permissions at the appropriate scope that your app requires. At runtime, your app can continue to use Azure AD and OAuth to authenticate application requests. You can find details at Office 365 app authentication concepts. You should plan for an upgrade path. Profind 1 6 0.
With this approach, you can choose to access the Outlook REST API by calling it directly in your Office 365 apps, or by using the Office 365 client libraries.
Upgrade path
The v2 authentication endpoint has been promoted from preview to Generally Available (GA) status for Outlook and Outlook.com developers.
If you have an in-production app that accesses Office 365 mailbox data, or if you are creating a new app for Office 365 orOutlook.com, plan to use the v2 authentication endpoint together with the latest Outlook endpoint (https://outlook.office.com/
, see more below) to take advantage of writing just one set of code for both organizational Office 365 and personal Outlook.com users.
If you have an in-production app that uses Windows Live API to access Outlook.com mailbox data, you must rewritethe app to use the the v2 authentication endpoint and the Outlook REST API. Because Windows Live API is being deprecated for Outlook.com, and Outlook.com users get their mailboxes enabled for the Outlook REST API, these users will get HTTP 404 errors when attempting to run such Windows Live API apps.
On the other hand, the Outlook REST API opens up new opportunities for you—you can choose from a list of common languages such as Node, Python, Swift, Java, and so on, write the app once, and capture both Outlook.com and Office 365 users on the web, iOS, Android, or Windows devices.
Note
If you intend your in-production app to continue to access only Outlook.com mailbox data, you can continue to usethe same Windows Live scopes to access most of the Outlook REST API. For more information, see Using Windows Live scopes and Outlook REST API to access Outlook.com mailbox data.
Regardless of the approach you use for app registration and user authorization, or whether your app targets Office 365 orOutlook.com mailbox data, the latest Outlook REST endpoint is in production and you can start using it in your REST API calls whenever you are ready:
https://outlook.office.com/api/{version}/{user_context}
Set For Ms Office 2 0 Online
The following Outlook REST endpoint will continue to work for a while for only Office 365 mailbox data:
https://outlook.office365.com/api/{version}/{user_context}
See more about supported REST actions, endpoints and versions below.
Important
Set For Ms Office 2 0 Download
- Basic authorization is no longer supported by the Outlook REST API endpoint
https://outlook.office.com
.Use the v2 authentication endpoint or Azure AD to do authorization and authentication for an app that uses the newOutlook REST API endpoint. - For optimal performance when using the new Outlook REST endpoint, add an
x-AnchorMailbox
header for every request and set itto the user's email address. For example:x-AnchorMailbox:john@contoso.com
- Because enabling mailboxes on Outlook.com for the Outlook REST API happens over a period of time, your existing Outlook.comaccount may take a while to get enabled. To test your app accessing data on Outlook.com mailboxes that have already beenenabled, you can request a new, enabled Outlook.com developer preview account by emailing outlookdev@microsoft.com.
- If your app accesses Outlook.com mailbox data, it should handle scenarios where the user's mailbox has not yet beenenabled for the Outlook REST API. In such situations, when you make a REST request, you would get an error like the following:
- HTTP error: 404
- Error code: MailboxNotEnabledForRESTAPI or MailboxNotSupportedForRESTAPI
- Error message: 'REST API is not yet supported for this mailbox.
- For code samples that use the v2 authentication endpoint, see dev.outlook.com.
Using Windows Live scopes and Outlook REST API to access Outlook.com mailbox data
If your in-production app for Outlook.com uses Windows Live scopes, and you don't intend to target Office 365 mailbox data,you can continue to use these Windows Live scopes with most of the Outlook REST API. The table below shows how Windows Live scopes map to the Outlook REST API scopes. Note that there isn't a Windows Live scope direct mapping for Mail.Read; your app can use wl.imap to access those Outlook REST API operations that require Mail.Read.
Windows Live scopes | Outlook REST API scopes |
---|---|
wl.basic | User.Read, Contacts.Read |
wl.calendars | Calendars.Read |
wl.calendars_update | Calendars.ReadWrite |
wl.contacts_create | Contacts.ReadWrite |
wl.contacts_calendars | Calendars.Read |
wl.emails | User.Read |
wl.events_create | Calendars.ReadWrite |
wl.imap | Mail.ReadWrite, Mail.Send |
Supported REST actions and endpoints
To interact with the Outlook REST API, you send HTTP requests that use a supported method: GET, POST, PATCH, or DELETE.POST and PATCH request bodies and server responses are sent in JSON payloads.
The path URL resource names and query parameters are case insensitive. However, values you assign, entity IDs,and other base64 encoded values are case sensitive.
All Outlook REST API requests use the following new root URL format:
https://outlook.office.com/api/{version}/{user_context}
All Outlook REST API requests use the following new root URL format:
https://outlook.office.com/api/{version}/{user_context}
With the appropriate user authorization, the REST API in this root URL provides access to mailbox data on Office 365 and Outlook.com. The rest of this article describes REST API in this endpoint.
If you have code that uses the pre-existing root URL https://outlook.office365.com/api/{version}/{user_context}
, your code will continue to work for a while for Office 365, but you should plan to switch to the new root URL.
Important
For optimal performance, when making a REST request using the new root URL, add an x-AnchorMailbox
header and set it to the user's email address. Also, handle the case where an Outlook.com user's mailbox has not yet been enabled for the Outlook REST API; check for the error codes MailboxNotEnabledForRESTAPI and MailboxNotSupportedForRESTAPI. See more information here.
Notes for developers in China
If you are developing apps for Office 365 in China, you should continue to use the API endpoints of Office 365 for China.
If you are creating apps for Outlook.com in China, try the v2 authentication endpoint, and use the following new Outlook REST endpoint:
https://outlook.office.com/api/{version}/{user_context}
.
Supported versions of API
Set For Ms Office 2 0 Free
{version}
represents the version of the Outlook REST API in the specified root URL. You can specify one of the following values:
v1.0. The is the earliest version in General Availability (GA) status and can be used in production code. An example URL is
http://outlook.office.com/api/v1.0/me/events
.v2.0. This version is also in GA status and can be used in production code. An example URL is
http://outlook.office.com/api/v2.0/me/events
. This version includes changes that may break v1.0, and additional API sets that have matured and been promoted from preview to GA status.beta. This version is in preview status and should not be used in production code. An example URL is
http://outlook.office.com/api/beta/me/events
. This version includes the latest API in GA, as well as additional API sets that are in preview, and that may change prior to finalization.
The majority of the REST operations in the Outlook REST API is supported and behaves the same way as described across the above listed versions.
Target user
With the exception of the User Photo REST API, {user_context}
is the currently signed-in user, as the Outlook REST API requests are always performed on behalf of the current user.
For the User Photo REST API, {user_context}
can be the signed-in user, or a user specified by a user ID.
Regardless of the set of Outlook REST API, you can specify {user_context}
in REST requests in one of the following ways:
With the
me
shortcut:/api/{version}/me
. The root URL becomeshttps://outlook.office.com/api/{version}/me
.With the
users/{upn}
format to pass the UPN or a proxy address of the signed-in user, such as:/api/beta/users/sadie@contoso.com
. In this example, the root URL would becomehttps://outlook.office.com/api/beta/users/sadie@contoso.com
.With the
users/{AAD_userId@AAD_tenandId}
format, utilizing the user ID and tenant ID in Azure Active Directory. For example,users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77
The root URL would becomehttps://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77
.
Usage is a matter of preference.
In server responses, the user context is identified in this format: users/{AAD_userId@AAD_tenandId}
.
Accessing item in a collection
The Outlook REST API supports two ways of specifying an item in an entity collection. They are evaluated identically,so usage is a matter of preference.
In the URL segment after the collection, for example:
/api/{version}/me/events/AAMkAGI3.
In parentheses as a quoted string, for example:
/api/{version}/me/events('AAMkAGI3.')
Use a client library to access the Outlook REST API
The Office 365 API client libraries make it easier to interact with the REST API:
They help manage authentication tokens and simplify the code needed to query and consume data on Office 365.
Shutting down of earlier preview endpoint
If you are already using https://outlook.office.com/api
or https://outlook.office365.com/api
as the root URL
to access Outlook REST API, this deprecation doesn't affect you. Read on if you are still using the earlierpreview endpoint https://outlook.office365.com/ews/odata
.
Unpack dmg file mac. The Outlook REST API moved from its initial preview to v1.0 general availability in October 2014. To complete thistransition, we shut down the old preview endpoint https://outlook.office365.com/ews/odata
onOctober 15, 2015.
We required all apps and services using the old endpoint https://outlook.office365.com/ews/odata
to move to https://outlook.office.com/api/v1.0
by October 15, 2015. v1.0 was the minimum general availability (GA) endpoint to move to by that date.
Alternatively, you can use the preferred GA endpoint v2.0 (https://outlook.office.com/api/v2.0
), or the previewendpoint (https://outlook.office.com/api/beta
) to try the latest APIs in preview status. Keep in mind that in general, API in preview status may change before finalization. If you use them, be prepared to verify features in your app and make appropriate changes. When in-preview APIs get finalized, you will be able to access these enhancements in a GA endpoint as well.
Next steps
Proceed to use the Outlook REST API:
- Streaming Notifications REST API reference (preview)