# Microsoft Graph API Reference

## Base URL
`https://graph.microsoft.com/v1.0`

## Authentication

Uses OAuth 2.0 device code flow for personal Microsoft accounts.

### Endpoints
- Device code: `https://login.microsoftonline.com/consumers/oauth2/v2.0/devicecode`
- Token: `https://login.microsoftonline.com/consumers/oauth2/v2.0/token`

### Scopes
- `Mail.Read` — Read emails
- `Mail.Send` — Send emails
- `Files.ReadWrite` — OneDrive access
- `User.Read` — User profile
- `offline_access` — Refresh tokens

## Mail API

### List messages
```
GET /me/mailFolders/inbox/messages?$top=10&$orderby=receivedDateTime desc
```

### Read message
```
GET /me/messages/{id}
```

### Send message
```
POST /me/sendMail
{
  "message": {
    "subject": "Subject",
    "body": {"contentType": "Text", "content": "Body"},
    "toRecipients": [{"emailAddress": {"address": "to@example.com"}}]
  }
}
```

### Search messages
```
GET /me/messages?$search="from:sender@example.com"
```

### List folders
```
GET /me/mailFolders
```

## OneDrive API

### List root
```
GET /me/drive/root/children
```

### List folder
```
GET /me/drive/root:/{path}:/children
```

### Get file metadata
```
GET /me/drive/root:/{path}
```

### Download file
Get the `@microsoft.graph.downloadUrl` from file metadata.

### Upload small file (<4MB)
```
PUT /me/drive/root:/{path}:/content
Content-Type: application/octet-stream

<file bytes>
```

### Create folder
```
POST /me/drive/root/children
{
  "name": "New Folder",
  "folder": {}
}
```

## Calendar API

### List events
```
GET /me/events?$top=10&$orderby=start/dateTime
```

### Create event
```
POST /me/events
{
  "subject": "Meeting",
  "start": {"dateTime": "2026-03-24T10:00:00", "timeZone": "Europe/Copenhagen"},
  "end": {"dateTime": "2026-03-24T11:00:00", "timeZone": "Europe/Copenhagen"}
}
```

## Error Handling

Common errors:
- `401 Unauthorized` — Token expired, need to refresh or re-auth
- `403 Forbidden` — Missing permissions
- `404 NotFound` — Resource doesn't exist
- `429 TooManyRequests` — Rate limited, back off

## Rate Limits

- Per-app: ~10,000 requests / 10 minutes
- Per-mailbox: ~10,000 requests / 10 minutes
- Throttled responses include `Retry-After` header