Microsoft Outlook API Essential Guide

What type of API does Microsoft Outlook provide?

Microsoft Outlook primarily uses REST APIs. Here are the key points:

REST APIs

• Microsoft Graph, which provides access to Outlook data, uses REST APIs.
• The Outlook REST APIs are available through both Microsoft Graph and the Outlook API endpoint (https://outlook.office.com/api).
• Microsoft recommends using the Microsoft Graph endpoint for accessing Outlook data, as it provides access to Outlook and many other Microsoft 365 services.

Transition from Outlook-specific APIs to Microsoft Graph

• The Outlook-specific REST endpoints will be fully decommissioned in March 2024.
• Microsoft is encouraging developers to migrate existing apps to use Microsoft Graph instead.

Summary

Microsoft Outlook primarily uses REST APIs, accessible through Microsoft Graph. While Outlook-specific REST endpoints still exist, they are being phased out in favor of the more comprehensive Microsoft Graph API. Developers should focus on using Microsoft Graph for accessing Outlook data going forward.

Does the Microsoft Outlook API have webhooks?

Yes, the official Microsoft Outlook API (Microsoft Graph API) supports webhooks for receiving notifications about changes to Outlook resources. Here are the key points about Outlook webhooks:

Supported Resources and Events

You can subscribe to change notifications for the following Outlook resources:

• Contacts
• Events (calendar items)
• Messages (emails)

The types of events you can subscribe to include:

• Created
• Updated
• Deleted

Creating a Subscription

To set up webhooks, you need to create a subscription by specifying:

• The resource you want to monitor (e.g. messages, events, contacts)
• The types of changes to notify about (created, updated, deleted)
• A notification URL where you'll receive the webhooks
• An expiration date for the subscription

Here's an example subscription request:

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/{id}/messages",
    "expirationDateTime": "2021-07-07T21:42:18.2257768+00:00",
    "clientState": "secretClientState"
}

Notification Delivery

When a change occurs, Microsoft Graph will send a notification to your specified URL within about 30 seconds, though this timing is not guaranteed.

Permissions

You'll need appropriate permissions to create subscriptions, such as Mail.Read for messages.

Additional Considerations

• There's a limit of 1000 active subscriptions per mailbox
• You can optionally receive resource data (message content, etc.) in the notifications
• Lifecycle notifications are available to help manage subscription expiration

Best Practices

• Implement validation of the notification URL when creating subscriptions
• Handle potential delays in notification delivery
• Renew subscriptions before they expire

In summary, Outlook webhooks provide a powerful way to receive near real-time notifications about changes to emails, calendar events, and contacts in Microsoft 365 and Outlook.com mailboxes.

Rate Limits and other limitations

Here are the key API rate limits for the Microsoft Outlook API:

General Limits

• 10,000 API requests per 10 minute period, per user/mailbox, per app ID
• 4 concurrent requests per mailbox
• 150 MB upload (PATCH, POST, PUT) per 5 minute period

Global Limit

• 130,000 requests per 10 seconds per app across all tenants

Outlook-specific Resources

The limits apply to Outlook-related resources accessed via Microsoft Graph, including:

• Mail resources
• Calendar resources
• Contact resources
• Attachment resources
• People and social resources
• Photo resources
• Group conversations

Tracking Usage

For the Outlook REST API endpoints (not Microsoft Graph), responses include headers to track usage:

• Rate-Limit-Limit: Maximum requests allowed per minute
• Rate-Limit-Remaining: Number of requests remaining in current window
• Rate-Limit-Reset: Time when current rate limit window resets (UTC)

Best Practices

• Monitor usage via response headers
• Implement error handling for 429 (Too Many Requests) responses
• Reduce number of requests if approaching limits
• Use batching when possible to combine multiple operations

Summary

The main limit to be aware of is 10,000 requests per 10 minutes per mailbox. Staying within this limit and implementing proper error handling for 429 responses will help ensure smooth API usage. The headers provided can be used to track current usage levels.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Microsoft Outlook API:

Current Status of Outlook REST API

1. The Outlook REST API v2.0 and beta endpoints have been deprecated.

2. Microsoft announced that they will fully deprecate Outlook REST v2.0 and beta endpoints on March 31, 2024.

3. After March 31, 2024, every call to the Outlook REST v2.0 and beta endpoints will result in an HTTP 410 (Gone) error.

Recommended API

1. Microsoft recommends migrating existing applications to use Microsoft Graph.

2. The Outlook Mail REST API is now part of Microsoft Graph. Developers should refer to the Microsoft Graph documentation for the latest API version and functionality.

Key Points to Consider

1. The v2.0 Outlook REST endpoint was fully decommissioned in November 2022.

2. If you are using Outlook REST API v2.0 or beta endpoints in your app, you should plan on transitioning to Microsoft Graph as soon as possible.

3. Microsoft Graph provides richer scenarios for Microsoft 365 services, including Outlook.

4. For guidance on transitioning from Outlook REST to Graph, refer to: https://aka.ms/FromOutlookRestToGraph.

Best Practices

1. Use the Microsoft Graph API for all new development related to Outlook and Office 365 services.

2. If you have existing applications using the Outlook REST API, plan to migrate them to Microsoft Graph before March 31, 2024.

3. When using Microsoft Graph, ensure you're using the latest version and following the documentation provided by Microsoft.

4. Keep an eye on Microsoft's official announcements and documentation for any future updates or changes to the API.

In conclusion, the most recent version of the Microsoft Outlook API is now part of Microsoft Graph, and developers should use Microsoft Graph for all new and existing Outlook-related development.

How to get a Microsoft Outlook developer account and API Keys?

To get a developer account for Microsoft Outlook and create an API integration, follow these steps:

1. Join the Microsoft 365 Developer Program

   • This provides you with an instant sandbox preconfigured with sample data
   • Allows you to start developing on the Microsoft 365 platform

2. Register Your Application

   • Sign in to the Azure portal using your Microsoft 365 Developer account credentials
   • In the left navigation pane, select "Microsoft Entra ID"
   • Select "App registrations" and then "New registration"
   • On the "Register an application" page:
     • Name your app
     • Choose who can use the app and access the API
     • Provide a redirect URL for user redirect after authentication, if needed

3. Configure Application Permissions

   • In the Azure Portal, go to "App registrations" > "All applications", select your application, and then select "API Permissions"
   • Click "Add a permission" and select "Microsoft Graph"
   • Choose the required permissions for your app (e.g., Mail.Read, Calendar.ReadWrite, etc.)
   • Select "Grant admin consent for [your tenant name]" to consent to the permissions

4. Obtain Authentication Credentials

   • Client ID (automatically generated when you register the app)
   • Client Secret (you'll need to generate this in the Azure portal)

5. Implement Authentication in Your App

   • Use the OAuth 2.0 flow to authenticate your app and obtain access tokens
   • Microsoft recommends using Microsoft Graph to access Outlook mail, calendar, and contacts

6. Make API Calls

   • Once authenticated, you can make calls to the Outlook REST APIs via Microsoft Graph
   • The base URL for API calls is:

     https://graph.microsoft.com/{version}
     

Key Points to Consider:

• Ensure your app is configured as multi-tenant if you want it to access data from multiple Office 365 tenants
• Store the tenant ID securely, as you'll need it for making API calls
• Implement proper access token management, including refreshing tokens when they expire
• Consider implementing a webhook listener if you need real-time notifications

Best Practices:

1. Use Microsoft Graph for accessing Outlook data whenever possible
2. Implement proper error handling and respect API throttling limits
3. Securely store authentication credentials and tokens
4. Keep your app's permissions to the minimum required for its functionality
5. Stay updated with the latest changes and improvements to the Microsoft Graph and Outlook APIs

What can you do with the Microsoft Outlook API?

Here's a list of data models you can interact with using the Microsoft Outlook API, along with what is possible for each:

Mail

• Read, create, update, and delete email messages
• Send email messages
• Get attachments and add attachments to messages
• Flag messages
• Categorize messages
• Search and filter messages

Calendar

• Read, create, update, and delete calendar events
• Get free/busy information
• Share calendars
• Set up recurring events
• Add attendees and resources to events

Contacts

• Read, create, update, and delete contacts
• Organize contacts into folders
• Add contact photos

Tasks

• Read, create, update, and delete tasks
• Organize tasks into task lists

Mail Folders

• Create, read, update, and delete mail folders
• Move messages between folders

User Profile

• Access user information like name, email address, etc.

Attachments

• Add, remove, and access file attachments on messages and events

Categories

• Create and manage categories for organizing items

Rules

• Create and manage inbox rules

Extended Properties

• Set custom properties on items

Push Notifications

• Subscribe to real-time notifications for changes

Groups

• Access group conversations, events, and files (in beta)

The API allows interacting with these data models through REST endpoints, supporting operations like create, read, update, delete, and query across the various Outlook data types. The specific capabilities may vary slightly between API versions.