Outlook API Documentation

Overview

Welcome to the Microsoft Outlook API documentation. This section provides comprehensive guides and reference materials for integrating with Outlook's powerful features. You can programmatically access and manage emails, calendars, contacts, and more, enabling you to build rich and dynamic applications.

The Outlook API is part of the broader Microsoft Graph API, providing a unified endpoint for accessing data across Microsoft 365 services. This allows for seamless integration with other services like OneDrive, SharePoint, and Teams.

Getting Started

To begin developing with the Outlook API, you'll need to register your application with Azure Active Directory (now Microsoft Entra ID) to obtain credentials. This process allows your application to securely authenticate and request permissions to access user data.

Follow these steps:

  1. Register your application in the Azure portal.
  2. Configure the necessary API permissions for your application (e.g., Mail.Read, Calendar.ReadWrite).
  3. Implement an authentication flow (e.g., OAuth 2.0) to obtain access tokens.
  4. Make requests to the Microsoft Graph API endpoint for Outlook data.
Note: Ensure your application adheres to the Microsoft identity platform best practices for secure and compliant development.

Core APIs

The core Outlook APIs provide access to the fundamental components of a user's Outlook profile.

Mail API

The Mail API allows you to send, receive, read, and manage emails. You can create new messages, move emails between folders, mark them as read or unread, and search for specific messages.

  • Sending Email: Use the /me/sendMail endpoint to send new emails.
  • Reading Emails: Access emails via /me/messages. You can filter and sort messages to retrieve specific data.
  • Managing Folders: Interact with mail folders using /me/mailFolders.
POST /me/sendMail
{
  "message": {
    "subject": "Hello World!",
    "body": {
      "contentType": "Text",
      "content": "This is a test email sent via the Outlook API."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "recipient@example.com"
        }
      }
    ]
  },
  "saveToSentItems": "true"
}

Calendar API

The Calendar API enables you to manage user events, appointments, and calendars. You can create, retrieve, update, and delete calendar events.

  • Accessing Events: Retrieve events from a user's primary calendar using /me/calendar/events.
  • Creating Events: Use the POST method on /me/calendar/events to create new calendar entries.
  • Managing Calendars: Access multiple calendars via /me/calendars.
GET /me/calendar/events?$filter=start/dateTime ge '2023-10-27T09:00:00Z'
&$filter=end/dateTime lt '2023-10-27T17:00:00Z'

Contacts API

The Contacts API allows you to work with user contacts. You can read, create, update, and delete contacts and contact folders.

  • Accessing Contacts: Retrieve contacts using /me/contacts.
  • Creating Contacts: POST to /me/contacts to add new contacts.
  • Contact Folders: Manage contacts within different folders via /me/contactFolders.

Advanced APIs

Explore more specialized APIs for enhanced functionality.

Mail Merge

While not a direct API, Outlook's mail merge functionality can be integrated with applications that prepare data for personalized email campaigns.

Outlook Add-ins

Develop add-ins that extend Outlook's functionality across desktop, web, and mobile clients. These add-ins can interact with Outlook data and external services.

Tip: The Office Add-ins platform offers extensive documentation and tools for building powerful extensions.

Outlook Rules API

Programmatically manage user-defined rules for processing incoming emails. This allows for automated organization and filtering of messages.

Authentication

All requests to the Outlook API must be authenticated. The primary method is through Microsoft Entra ID using OAuth 2.0 flows. Ensure you handle access tokens and refresh tokens securely.

Common OAuth 2.0 flows include:

  • Authorization Code Flow (for web and native apps)
  • Client Credentials Flow (for daemon services)
  • On-Behalf-Of Flow

Refer to the Microsoft identity platform documentation for detailed guidance on implementing these flows.

Error Handling

When an API request fails, the Microsoft Graph API returns an error response. These responses typically include an HTTP status code, an error code, and a user-friendly error message.

Common error codes include:

Code Description
InvalidRequest The request was malformed or invalid.
Unauthorized The client does not have permission to perform the operation.
Forbidden The user or application does not have sufficient permissions.
NotFound The requested resource was not found.
TooManyRequests The rate limit for the API has been exceeded.

Always implement robust error handling in your applications to gracefully manage API failures and provide feedback to the user.

SDK & Samples

Microsoft provides Software Development Kits (SDKs) for various platforms to simplify integration with the Microsoft Graph API, including Outlook endpoints.

Explore the following resources: