Connecting OAuth Outlook mailboxes via API

A Comprehensive Guide to Set Up OAuth2 for Outlook Mailboxes Using the Warmy API

Scheme for Creating OAuth2 Tokens

To integrate your mailboxes using OAuth2, you'll need to create and manage tokens. Below is the required data for connection and how to obtain it:

Required Data for Connection

1. client_id: A unique identifier for the application in Azure AD.
2. client_secret: The application secret key (used for server-side integrations only).
3. access_token: Token for interacting with the API.
4. refresh_token: Token to refresh the access_token after it expires.

---

Example Request for Integration

Here's an example of how to integrate mailboxes with the Warmy API:

---

Getting Data by Registering an Application in Azure AD

1. Registering an Application in Azure Active Directory

1. Sign in to the Azure Portal.
2. Navigate to Azure Active Directory > App Registrations.
3. Click New Registration and fill in the required fields:
   • Name: Enter your application name.
   • Redirect URI: Add a redirect URL (e.g., https://yourapp.com/oauth-callback).
4. Click Register.

---

2. Retrieving client_id and client_secret

1. After registration, open the application in App Registrations.

2. Navigate to the Overview tab:

   • Copy the Application (client) ID as client_id.

   

3. Go to Certificates & Secrets > New Client Secret:

   • Enter a description (e.g., "Warmy Secret").
   • Select an expiration date (e.g., 6 months).
   • Click Add and copy the generated value (this is your client_secret).

   

---

3. Setting Up API Permissions

1. In the API Permissions tab, click Add a permission.

2. Select Microsoft Graph > Delegated permissions and add the following scopes:

   • Mail.Read: Access to incoming messages.
   • Mail.Send: Ability to send emails.
   • offline_access: Permission to receive a refresh_token.
   • User.Read: Access user account information.
   • Mail.ReadWrite (if you need to modify emails).

3. Click Grant admin consent to confirm the permissions.

   

---

OAuth2 Token Generation

Step 1: Receiving auth_code

To get an authorization code (auth_code), use the following URL to redirect the user to the authorization page Microsoft:

Request Parameters
Pass the following parameters to the URL via the query string:

Parameter	Description
client_id	Application identifier obtained during Azure registration.
response_type	Use code to request an authorization code.
redirect_uri	URL to redirect after successful authorization (must match the Azure AD app settings).
scope	Permissions requested (e.g., offline_access https://graph.microsoft.com/.default).
state	(Optional) Unique parameter to identify the session.

A tenant is an identifier or domain for the organization in Azure (for example: common, organizations, or specific ID). A tenant can be found in the Azure Portal under Azure Active Directory > Overview.

An example of a query to get auth_code:

1. Follow the link and log in to your Microsoft account.

2. After authorization, you are redirected to the specified redirect_uri with auth_code in the query string.

3. The response will return the auth_code in the request parameters, example:

   https://your-redirect-uri.com/?code={auth_code}&state={state}


---

Step 2: Exchanging auth_code for access_token

Send a POST request to exchange the auth_code for an access_token:

Request Parameters:

A successful response will include:

• access_token: A token obtained during authentication, used for authorizing API requests and verifying the user's identity.
• refresh_token: To refresh the access_token.
• expires_in: The lifetime of the access_token in seconds.

---

Step 3: Update access_token (if necessary)

Send a POST request to the same endpoint /token, but with the parameter:

---

Common Errors and Solutions

Error	Solution
Invalid redirect URI	Ensure the redirect_uri matches the one registered in Azure AD.
Invalid client secret	Verify the client_secret is correct and hasn't expired.
Repeated consent prompts	Confirm admin rights via Grant admin consent in the Azure portal.
Prompt=consent issue	The prompt=consent parameter explicitly forces the consent screen to appear, regardless of whether the permissions have already been granted or skipped through configuration. If this parameter is included in the authorization request, the user or administrator will always be prompted to approve the requested permissions again. Remove this parameter unless you explicitly need to re-request consent.

---

Conclusion

By following these steps, you can securely integrate Outlook mailboxes with Warmy.io using OAuth2 authentication. This integration ensures seamless email operations while maintaining security and scalability.