Executive Summary

Integrating your work email with PyjamaHR—whether via SMTP credentials or OAuth (Gmail/Outlook)—is essential for seamless candidate communication, automated notifications, and tracking sent emails. However, users often encounter errors like “Authentication failed,” “Integration Failed,” or OAuth scope/permission issues. This guide provides a comprehensive, step-by-step approach to diagnosing and resolving these errors, ensuring your email integration works reliably and securely.

Detailed Overview

What Are SMTP and OAuth Integrations in PyjamaHR?

SMTP Integration: Lets you connect any work email (including custom domains, Zoho, Amazon SES, etc.) by entering SMTP server details, credentials, and security settings. This enables PyjamaHR to send emails as if from your official address.
OAuth Integration: Used for Gmail and Outlook accounts, this method uses secure authorization (OAuth) to grant PyjamaHR permission to send emails and access your mailbox, without sharing your password.

Why Integrate?
- Ensures all candidate emails come from your real work address.
- Enables tracking of sent emails and replies within PyjamaHR.
- Supports features like automated application confirmations, interview scheduling, and more.

Where It Fits in PyjamaHR:
- Email integration is managed under Settings > Email.
- Impacts candidate communication, notification flows, and team collaboration.

Step-by-Step Guide: Diagnosing and Fixing SMTP Credential & OAuth Scope Errors

Prerequisites

Access to your work email account and its SMTP settings (host, port, username, password).
For OAuth: Ability to log in to your Gmail or Outlook account and grant permissions.
Super Admin or Admin access in PyjamaHR.

1. Identify the Type of Integration and Error

Common Error Messages:
- “Authentication failed. Please verify your credentials and try again.”
- “Integration Failed”
- “Could not connect due to an SMTP issue. Check settings or contact your provider.”
- “OAuth scope error” or “Permission denied”

Where to See Errors:
- Immediately after attempting to integrate in Settings > Email
- When sending emails and they do not appear in the “Sent” folder or candidate mail history

2. Fixing SMTP Credential Errors

a. Double-Check SMTP Details

Email Field: Enter the “From” email address you want to send as (not always the same as SMTP username).
- Example: For Amazon SES, the “From” address must be verified in SES.
SMTP Host: e.g., smtp.yourdomain.com, smtp.zoho.com, email-smtp.us-east-1.amazonaws.com (for SES)
SMTP Port: Usually 587 (TLS), 465 (SSL), or as specified by your provider.
Username: The SMTP username (may differ from your email address).
Password: The SMTP password or app-specific password (not your regular login password if 2FA is enabled).
SSL/TLS: Select as per your provider’s recommendation.

Common Mistake: Entering the email address as the username when they are different (e.g., Amazon SES).

b. Test Credentials Outside PyjamaHR

Use a tool like Gmass SMTP Test to verify your credentials independently.
If it works outside but not in PyjamaHR, double-check field mapping (see above).

c. Check for Two-Factor Authentication (2FA) or App Passwords

If your email provider enforces 2FA, you may need to generate an “App Password” for SMTP access.
For Gmail, Outlook, Zoho, etc., regular passwords may not work if 2FA is enabled.

d. Provider-Specific Requirements

Amazon SES: “From” address must be verified in SES; username and email may differ.
Zoho/Custom Domains: Ensure SMTP is enabled for your account; some providers require whitelisting PyjamaHR’s IP/domain.

e. Firewall/Whitelist Issues

Some providers block SMTP access by default. Ask your IT/email admin to whitelist PyjamaHR if needed.

f. Port and Security Protocol

Try both 587 (TLS) and 465 (SSL) if unsure.
If you get “Could not connect,” the port or protocol may be blocked or incorrect.

3. Fixing OAuth Scope and Permission Errors (Gmail/Outlook)

a. Disconnect and Reconnect

Go to Settings > Email in PyjamaHR.
Click “Disconnect” on the current integration.
Reconnect and carefully follow the prompts, ensuring you select “Allow” for all requested permissions.

b. Select the Correct Account and Grant All Permissions

If prompted, select the correct Google/Microsoft account.
When asked for permissions, use “Select All” or manually check all boxes.
If you skip permissions, integration will fail or have limited functionality.

c. Check for Existing Calendar/Email Conflicts

If your Google Calendar is integrated with a different email than your Gmail, integration may fail.
- Solution: Disconnect both, then reconnect using the same email for both Calendar and Gmail.

d. Admin Approval Required (for Workspace/Business Accounts)

If you see “Admin approval required,” your organization’s admin must approve PyjamaHR’s app in Google Workspace or Microsoft Entra/Azure.
- Share the error message and request with your IT admin.

e. OAuth Prompt Parameters

If you repeatedly see approval prompts, your admin may need to remove prompt=consent or prompt=admin_consent from the OAuth URL (advanced, for IT admins).

4. Verifying Integration

After successful integration, send a test email to yourself or a colleague.
Check:
- Email is sent from your work address.
- Email appears in the “Sent” folder of your email client (for SMTP).
- Email is logged in the candidate’s mail history in PyjamaHR.

Advanced Usage & Best Practices

Use App Passwords for SMTP if your provider supports 2FA.
Verify “From” Address in your SMTP provider (especially Amazon SES).
Keep Credentials Secure: Never share SMTP passwords; use app-specific passwords where possible.
Monitor Integration Health: If emails stop sending or disappear from “Sent,” re-authenticate or check for expired tokens.
For Team Accounts: Each user should integrate their own email for accurate tracking and reply management.
Bulk Email Sending: Some providers (Gmail, Zoho) limit the number of emails sent per day/hour. Exceeding this may cause disconnection or fallback to PyjamaHR’s default sender.

Troubleshooting & Common Issues

Error Messages & Solutions

Error Message	Likely Cause	Solution
Authentication failed. Please verify your credentials and try again.	Wrong username/password, 2FA not handled, app password required	Double-check credentials, use app password, verify with provider
Could not connect due to an SMTP issue. Check settings or contact your provider.	Wrong host/port, firewall, SSL/TLS mismatch	Confirm SMTP host/port, try both SSL/TLS, ask IT to whitelist PyjamaHR
Integration Failed (OAuth)	Permissions not granted, wrong account, admin approval needed	Disconnect, reconnect, select all permissions, ensure correct account, ask admin for approval
Sent emails not appearing in Sent folder	SMTP “From” address mismatch, provider limitation	Ensure “From” address matches verified sender, check provider’s sent folder policy
Emails stop after X messages	Provider rate limit, token expiry	Wait/reset, re-authenticate, check provider’s sending limits
OAuth scope error	Permissions not granted, admin block	Reconnect, select all permissions, ask admin to approve app

What If Scenarios

What if my SMTP username and email are different?
- Enter the correct username in the “Username” field and the desired “From” address in the “Email” field.
What if I can’t find the right port or protocol?
- Try both 587 (TLS) and 465 (SSL). Check your provider’s documentation.
What if my email provider says the problem is on PyjamaHR’s side?
- Test credentials with an external tool. If they work, share the results with PyjamaHR support for further investigation.
What if I use a group or alias email?
- Only users added to the group will receive emails. For sending, use a real mailbox with SMTP access.

Comprehensive FAQ

1. What does the “Email” field mean in SMTP setup?
- It’s the “From” address for outgoing emails. For some providers (e.g., Amazon SES), this must be a verified address.

2. My SMTP username and email are different. Which do I use?
- Enter your SMTP username in the “Username” field and your desired “From” address in the “Email” field.

3. Why do I get “Authentication failed” even with correct credentials?
- Possible reasons: 2FA enabled (use app password), wrong port/protocol, provider blocks SMTP, or username/email mismatch.

4. How do I know if my integration is working?
- Send a test email. It should appear in your “Sent” folder and in the candidate’s mail history in PyjamaHR.

5. Why are sent emails missing from my email client’s Sent folder?
- Some providers don’t save SMTP-sent emails in Sent by default. Check provider settings or use OAuth integration for Gmail/Outlook.

6. What if I need to change the integrated email?
- Disconnect the current integration in Settings > Email, then reconnect with the new email.

7. Why do I need admin approval for OAuth integration?
- For business accounts, your IT admin must approve PyjamaHR’s app in Google Workspace or Microsoft Entra/Azure.

8. Can I use a group/alias email for sending?
- Only if the group supports SMTP sending and you have access. For receiving, only group members get the emails.

9. Why do emails go to spam or promotions?
- This depends on your provider’s spam filters and email content. Authenticating via OAuth and using a verified sender helps.

10. What if I exceed my provider’s sending limits?
- PyjamaHR may fall back to its own sender or disconnect your integration. Check your provider’s daily/hourly limits.

11. Why do I see “prompt=consent” or “prompt=admin_consent” in OAuth URLs?
- These parameters force the approval prompt. Your admin may need to remove them for smoother integration.

12. Can I integrate more than one email per user?
- Each user can integrate one work email at a time for sending and tracking.

Email Template Management: Create and manage templates in Settings > Email Templates for consistent communication.
Team Member Access: Each user should integrate their own email for accurate tracking.
Calendar Integration: For interview scheduling, ensure the same email is used for both email and calendar integrations.
Bulk Import Candidates: Ensure email integration is set up before sending bulk communications.
Help Center Articles:

Summary Table: Quick Fixes for Common Scenarios

Scenario	Solution
SMTP “Authentication failed”	Double-check username/password, use app password, verify port/protocol, check 2FA
OAuth “Integration Failed”	Disconnect, reconnect, select all permissions, ask admin for approval
Emails missing from Sent	Use OAuth if possible, check provider’s sent folder policy
Provider says “problem is on PyjamaHR’s side”	Test credentials externally, share results with support
Need to change integrated email	Disconnect and reconnect with new email in Settings

When to Contact Support

After following all steps, integration still fails.
You receive unclear or persistent error messages.
Your provider confirms all settings are correct but PyjamaHR still cannot connect.
You need help with admin approval for OAuth apps.

Contact: Use in-app chat or email [email protected] with screenshots, error messages, and details of your setup.

By following this guide, you can resolve nearly all SMTP credential and OAuth scope errors in PyjamaHR, ensuring reliable, professional candidate communication and a seamless recruitment workflow.

Fixing SMTP Credential and OAuth Scope Errors in PyjamaHR: The Complete Troubleshooting Guide