Outlook API

The Microsoft Graph Outlook APIs enable you to access and manage email, calendar, contacts, and tasks for a user. This API allows for rich integration of communication and scheduling functionalities into your applications.

Getting Started

To start using the Outlook APIs, you'll need to:

  1. Register your application in the Azure portal.
  2. Obtain an access token using OAuth 2.0.
  3. Make requests to the Microsoft Graph endpoint for Outlook resources.

For detailed instructions on authentication and authorization, please refer to the Microsoft Graph authentication documentation.

Key Concepts

Endpoints

Messages

GET List Messages

Retrieves a collection of message objects in a specified folder.

/me/mailFolders/{folder-id}/messages
Parameters
Name Type Description
folder-id String The ID of the mail folder to retrieve messages from. Use inbox for the inbox.
$filter String OData filter clause to filter messages (e.g., isRead eq false).
$select String Comma-separated list of properties to return (e.g., subject,from,receivedDateTime).
Example Request
GET https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$select=subject,receivedDateTime&$filter=isRead eq false
Example Response
{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('user%40example.com')/mailFolders('inbox')/messages(subject,receivedDateTime)", "value": [ { "id": "AAMkAGRiZmQ4ZjQ4LWQwNjMtNGFiYy05NzRjLWI0YmRlNzU1NjRhYwAuAAAAAAAbN0Y8tS8iSJ38tG_CjJtXAQDJz9U9i7fBRpI59sQk_0EAAAJJ9mFAAA=", "subject": "Project Update Meeting", "receivedDateTime": "2023-10-27T10:30:00Z" }, { "id": "AAMkAGRiZmQ4ZjQ4LWQwNjMtNGFiYy05NzRjLWI0YmRlNzU1NjRhYwAuAAAAAAAbN0Y8tS8iSJ38tG_CjJtXAQDJz9U9i7fBRpI59sQk_0EAAAJJ9mfwAA=", "subject": "Regarding your recent inquiry", "receivedDateTime": "2023-10-26T15:00:00Z" } ] }

GET Get Message

Retrieves a specific message by its ID.

/me/messages/{message-id}
Parameters
Name Type Description
message-id String The unique identifier of the message.
$select String Comma-separated list of properties to return.
Example Request
GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGRiZmQ4ZjQ4LWQwNjMtNGFiYy05NzRjLWI0YmRlNzU1NjRhYwAuAAAAAAAbN0Y8tS8iSJ38tG_CjJtXAQDJz9U9i7fBRpI59sQk_0EAAAJJ9mFAAA=?$select=subject,body

POST Send Message

Sends a new message or forwards/replies to an existing message.

/me/sendMail
Request Body
Property Type Description
message Object The message object containing recipients, subject, and body.
saveToSentItems Boolean Optional. If true, the message is saved to the Sent Items folder. Defaults to true.
Example Request Body

{
  "message": {
    "subject": "Hello from the API",
    "body": {
      "contentType": "HTML",
      "content": "
Greetings!
This is a test email sent via the Outlook API.
"
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "recipient@example.com"
        }
      }
    ]
  },
  "saveToSentItems": "true"
}

Calendars

Manage user calendars and events.

GET List Events

Retrieves a collection of event objects in a specified calendar.

/me/calendars/{calendar-id}/events
Example Request
GET https://graph.microsoft.com/v1.0/me/calendars/{calendar-id}/events?$filter=isOrganizer eq true

POST Create Event

Creates a new event in a user's calendar.

/me/events
Example Request Body

{
  "subject": "Team Meeting",
  "body": {
    "contentType": "HTML",
    "content": "Discussing Q4 roadmap."
  },
  "start": {
    "dateTime": "2023-11-01T09:00:00",
    "timeZone": "Pacific Standard Time"
  },
  "end": {
    "dateTime": "2023-11-01T10:00:00",
    "timeZone": "Pacific Standard Time"
  },
  "location": {
    "displayName": "Conference Room A"
  },
  "attendees": [
    {
      "emailAddress": {
        "address": "attendee@example.com",
        "name": "Attendee Name"
      },
      "type": "required"
    }
  ]
}

Contacts

Manage user contacts.

GET List Contacts

Retrieves a collection of contact objects.

/me/contacts
Example Request
GET https://graph.microsoft.com/v1.0/me/contacts?$filter=startswith(displayName, 'A')
Note: The /me endpoint represents the signed-in user. You can also use specific user IDs with the appropriate permissions.
Tip: Explore the Microsoft Graph Explorer to test these API endpoints interactively.