API Documentation

Learn how to programmatically fetch email messages and OTP codes from Outlook/Hotmail accounts using our endpoints.

Quick Reference

Endpoint Name	Functionality	Strength
1. Auto-Fetch Mail Code	Fetch mail & Extract Code	Best for stability (Auto fallback Graph/IMAP)
2. Fast Graph Code API	Get code via Graph	Extremely high performance response
3. Full Web Client API	List + Full Content	Ideal for building a custom email UI
4. Explicit Token Renewal	Force Token Refresh	Guarantees fresh token without expiration checks

Authentication & Token Refresh

All endpoints require Microsoft OAuth2 credentials. We support Automatic Token Refreshing.

Need to refresh a token?

No separate endpoint is needed. Simply send your refresh_token and client_id to any endpoint. If your access token is expired, the system will obtain a new one automatically and return it in the response as new_access_token.

Important Permissions

For IMAP OAuth2, ensure your scope includes: https://outlook.office.com/IMAP.AccessAsUser.All offline_access.

2. Fast Graph Code API

Specifically optimized for getting code mail at high speed using the native Microsoft Graph interface.

POST https://getmail.nguonnick.com/api/graph-messages

Parameters

Name	Type	Description
email Required	String	The target email address.
refresh_token Required	String	OAuth2 refresh token.
client_id Required	String	Application client ID.

Request Example

{
  "email": "[email protected]",
  "refresh_token": "M.C518...",
  "client_id": "5464fghj..."
}

1. Auto-Fetch Mail Code

The smartest endpoint for automation. It automatically parses messages to get code mail and handles connection switching if Graph fails.

POST https://getmail.nguonnick.com/api/get-oauth2

Parameters

Name	Type	Description
email Required	String	The target email address.
refresh_token Required	String	OAuth2 refresh token.
client_id Required	String	Application client ID.

Note: This endpoint is a proxy to a high-performance retrieval service, ensuring maximum compatibility with Hotmail, Outlook, and Office365 accounts.

Request Example

{
  "email": "[email protected]",
  "refresh_token": "M.C518...",
  "client_id": "5464fghj..."
}

Success Response

{
  "status": true,
  "messages": [
    {
      "uid": "123",
      "date": "2024-02-13T10:00:00Z",
      "from": [{ "name": "Facebook", "address": "security@..." }],
      "subject": "Your security code",
      "code": "56924",
      "message": "..."
    }
  ]
}

3. Full Web Client API

A comprehensive API for building web interfaces and getting code mail. Allows listing all messages and viewing full HTML content of any selected email.

GET https://getmail.nguonnick.com/api

Query Parameters

Name	Type	Description
action	String	'list' (default) or 'detail'.
method	String	'graph' (default) or 'imap'.
id	String	Message ID (required for 'detail').

Headers

Name	Required	Description
Authorization	Yes	Bearer [Access Token]
X-Refresh-Token	Yes	For auto-refreshing expired tokens.
X-Client-Id	Yes	Azure App Client ID.

List Messages Example

curl "https://getmail.nguonnick.com/api?method=graph&action=list" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "X-Refresh-Token: [REFRESH_TOKEN]" \
  -H "X-Client-Id: [CLIENT_ID]"

Get Detail Example

curl "https://getmail.nguonnick.com/api?method=graph&action=detail&id=..." \
  -H "Authorization: Bearer [TOKEN]" ...

4. Explicit Token Renewal API

Force the system to obtain a new Access Token immediately from Microsoft Azure, even if the current one is still technically valid.

GET https://getmail.nguonnick.com/api?method=renew

Query Parameters

Name	Required	Description
method	Yes	Must be `renew`.

Headers

Name	Required	Description
X-Refresh-Token	Yes	Azure Refresh Token.
X-Client-Id	Yes	Azure App Client ID.

Pro Tip: You can also send the X-Force-Refresh: true header to any endpoint to achieve the same result while fetching messages.

Token Renewal Example

curl "https://getmail.nguonnick.com/api?method=renew" \
  -H "X-Refresh-Token: [REFRESH_TOKEN]" \
  -H "X-Client-Id: [CLIENT_ID]"

Key Response Field

{
  "new_access_token": "EwA4BM16BAA...",
  "value": [...] 
}