Custom OAuth Integration Guide for WarmUpInbox

This guide explains how to set up Gmail or Microsoft Outlook inboxes using your own OAuth applications instead of WarmUpInbox's shared OAuth credentials.

🎯 Why Use Custom OAuth Integration?

Enterprise Control: Utilize your own verified OAuth applications.
Enhanced Security: Ideal for organizations with specific security needs.
Bypass Verification Issues: Avoid reliance on WarmUpInbox's OAuth verification status.

📋 Prerequisites

Active WarmUpInbox account with API access.
Administrative access to Google Cloud Console or Microsoft Azure.
Basic understanding of OAuth 2.0 concepts.
API client (Postman, curl, or custom application).

🔵 Google Gmail Integration

Step 1: Create a Google Cloud Project

Go to Google Cloud Console.
Click "Select a project" → "New Project".
Enter the project name (e.g., "WarmUpInbox Integration").
Click "Create".

Step 2: Enable Gmail API

In your project, go to "APIs & Services" → "Library".
Search for "Gmail API".
Click on it and press "Enable".

Step 3: Configure OAuth Consent Screen

Go to "APIs & Services" → "OAuth consent screen".
Choose "External" (if you don’t have Google Workspace).
Fill in the required fields:
- App name: Your application name.
- User support email: Your email.
- Developer contact information: Your email.
Click "Save and Continue".

Step 4: Add Required Scopes

Click "Add or Remove Scopes".
Add these essential scopes:
Click "Update" → "Save and Continue".

Step 5: Create OAuth Credentials

Go to "APIs & Services" → "Credentials".
Click "Create Credentials" → "OAuth 2.0 Client IDs".
Choose "Web application".
Add redirect URI: http://localhost:8080 (or your preferred URL).
Click "Create".
Save the Client ID and Client Secret – you'll need these!

Step 6: Get Access and Refresh Tokens

Create the authorization URL:

https://accounts.google.com/o/oauth2/auth?
client_id=YOUR_CLIENT_ID&
redirect_uri=http://localhost:8080&
scope=https://www.googleapis.com/auth/gmail.readonly%20https://www.googleapis.com/auth/gmail.send%20https://www.googleapis.com/auth/gmail.modify&
response_type=code&
access_type=offline&
prompt=consent

Replace YOUR_CLIENT_ID with your actual client ID.
Open this URL in a browser and authorize your Gmail account.
Copy the code parameter from the redirect URL.
Exchange the code for tokens:

curl -X POST https://oauth2.googleapis.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri=http://localhost:8080"

Save the access_token and refresh_token from the response.

Step 7: Create Inbox via WarmUpInbox API

curl -X POST https://api.warmupinbox.com/v2/inboxes/advanced \
  -H "Authorization: Bearer YOUR_WARMUPINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "sender_first": "Your",
    "sender_last": "Name",
    "plan": "basic",
    "custom_oauth": {
      "client_id": "YOUR_GOOGLE_CLIENT_ID",
      "secret_id": "YOUR_GOOGLE_CLIENT_SECRET"
    },
    "google": {
      "access_token": "YOUR_ACCESS_TOKEN",
      "refresh_token": "YOUR_REFRESH_TOKEN"
    },
    "frequency": {
      "starting_baseline": 4,
      "increase_per_day": 4,
      "max_sends_per_day": 50,
      "reply_rate": 30
    }
  }'

🔷 Microsoft Outlook Integration

Step 1: Register Application in Azure

Go to Azure Portal.
Navigate to "Azure Active Directory" → "App registrations".
Click "New registration".
Fill in details:
- Name: Your application name.
- Supported account types: Choose the appropriate option.
- Redirect URI: http://localhost:8080 (Web).
Click "Register".

Step 2: Configure API Permissions

In your app, go to "API permissions".
Click "Add a permission" → "Microsoft Graph".
Choose "Delegated permissions".
Add these essential permissions:

Mail.ReadWrite
Mail.Send
MailboxSettings.ReadWrite
User.Read
email
openid
profile

5. Click "Add permissions".

6. Click "Grant admin consent" (if you're an admin).

Step 3: Create Client Secret

Go to "Certificates & secrets".
Click "New client secret".
Add a description and choose expiration.
Click "Add".
Copy the secret value immediately – it won’t show again!

Step 4: Get Authorization Code

Create the authorization URL:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=YOUR_CLIENT_ID&
response_type=code&
redirect_uri=http://localhost:8080&
response_mode=query&
scope=https://graph.microsoft.com/Mail.ReadWrite%20https://graph.microsoft.com/Mail.Send%20https://graph.microsoft.com/MailboxSettings.ReadWrite%20https://graph.microsoft.com/User.Read%20email%20openid%20profile&
prompt=consent

2. Replace YOUR_CLIENT_ID and open the URL in a browser.

3. Authorize and copy the code from the redirect URL.

Step 5: Get Token Cache

This is the complex part. Use Microsoft's MSAL library to generate the token cache. Here’s a Node.js example:

const msal = require("@azure/msal-node");
 
const clientConfig = {
  auth: {
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    authority: "https://login.microsoftonline.com/common",
  },
};
 
const pca = new msal.ConfidentialClientApplication(clientConfig);
 
const tokenRequest = {
  code: "YOUR_AUTHORIZATION_CODE",
  scopes: [
    "https://graph.microsoft.com/Mail.ReadWrite",
    "https://graph.microsoft.com/Mail.Send",
  ],
  redirectUri: "http://localhost:8080",
};
 
pca
  .acquireTokenByCode(tokenRequest)
  .then((response) => {
    // Get the token cache
    const tokenCache = pca.getTokenCache().serialize();
    console.log("Token Cache:", tokenCache);
  })
  .catch((error) => {
    console.log(error);
  });

Step 6: Create Inbox via WarmUpInbox API

curl -X POST https://api.warmupinbox.com/v2/inboxes/advanced \
  -H "Authorization: Bearer YOUR_WARMUPINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "sender_first": "Your",
    "sender_last": "Name",
    "plan": "basic",
    "custom_oauth": {
      "client_id": "YOUR_MICROSOFT_CLIENT_ID",
      "secret_id": "YOUR_MICROSOFT_CLIENT_SECRET"
    },
    "office": {
      "token_cache": "YOUR_SERIALIZED_TOKEN_CACHE_JSON_STRING"
    },
    "frequency": {
      "starting_baseline": 4,
      "increase_per_day": 4,
      "max_sends_per_day": 50,
      "reply_rate": 30
    }
  }'

Common Issues and Solutions

Google Issues

Problem: "Access blocked: This app's request is invalid"

Solution: Ensure all required scopes are added and the consent screen is properly configured.

Problem: "invalid_grant" error

Solution: Make sure you're using access_type=offline and prompt=consent in the authorization URL.

Problem: "insufficient_scope" error

Solution: Verify that you've added all three required Gmail scopes.

Microsoft Issues

Problem: "AADSTS65001: The user or administrator has not consented"

Solution: Ensure admin consent is granted for all required permissions.

Problem: "invalid_client" error

Solution: Double-check that the client ID and secret are correct.

Problem: Token cache format issues

Solution: Ensure you're using the MSAL library to generate the proper token cache format.

General Issues

Problem: 401 Unauthorized from WarmUpInbox API

Solution: Verify that your WarmUpInbox API key is correct and has the proper permissions.

Problem: 400 Bad Request - missing fields

Solution: Ensure you're providing both custom_oauth AND either google or office configurations.

🔒 Security Best Practices

Store credentials securely: Never expose client secrets in client-side code.
Use HTTPS: Always use HTTPS in production redirect URIs.
Limit scopes: Only request the minimum required permissions.
Monitor usage: Regularly check OAuth application usage in cloud consoles.

📞 Support

If you encounter issues:

Verify all required scopes are properly configured.
Check that both credentials AND tokens are provided in the API call.
Ensure your OAuth application has proper permissions in Google/Microsoft.
For Google integrations: Remember that you typically need less verification for internal apps.
Contact WarmUpInbox support with specific error messages if problems persist.

🎉 Success!

Once configured properly, your custom OAuth integration will:

- ✅ Bypass WarmUpInbox's OAuth verification limitations

- ✅ Provide enhanced security and control

- ✅ Work seamlessly with WarmUpInbox's warmup system

Your inbox will now be ready for email warmup using your own OAuth credentials!