Onboarding task notification emails not sending after cloud migration-SMTP config and notification rules checked

HCM UKG Pro
, , , , , , , ,
1

Since migrating to UKG Pro cloud (UP 2022.2), our onboarding task notification emails have completely stopped working. New hires aren’t receiving their welcome emails or task assignments, which is causing significant onboarding delays.

I’ve verified the notification templates are still active and the SMTP settings look correct in the admin panel. However, when I check the notification logs, I’m seeing connection failures:


SMTP Error: Connection timeout to relay.ukgpro.cloud:587
Auth failed: Unable to establish TLS connection
Retry attempts: 3/3 failed

Our IT team confirmed they haven’t changed any firewall rules on our end. Could this be related to cloud-specific SMTP relay configuration or third-party authentication requirements? The templates worked fine in our on-prem environment. Anyone else experienced this after cloud migration?

2

The SMTP relay endpoints are completely different in cloud versus on-prem. You need to whitelist the new cloud SMTP relay servers in your firewall. UKG Pro cloud uses relay.ukgpro.cloud and backup-relay.ukgpro.cloud, both requiring outbound access on port 587 with TLS 1.2 or higher. Check with your network team to ensure these endpoints are allowed through your corporate firewall.

3

Beyond just whitelisting the relay servers, you need to configure SPF and DKIM records for the UKG cloud domain. The cloud platform sends emails on behalf of your organization, so your DNS needs to authorize relay.ukgpro.cloud as a valid sender. Without proper SPF/DKIM setup, even if the SMTP connection works, your emails might get blocked by recipient mail servers or end up in spam folders. Add this to your DNS: ‘v=spf1 include:_spf.ukgpro.cloud ~all’

4

For Microsoft 365 OAuth setup, you need to register UKG Pro as an app in Azure AD. Log into Azure Portal > App Registrations > New Registration. Set the redirect URI to your UKG instance URL + ‘/oauth/callback’. After registration, generate a client secret and note the Application (client) ID. Then in UKG Pro, go to System Configuration > External Integrations > Email Provider and enter these credentials. You’ll also need to grant the app ‘Mail.Send’ API permissions in Azure AD. The UKG documentation has a step-by-step guide in the ‘Cloud Email Configuration’ section.

5

I had the exact same issue. The TLS connection failure usually means your SMTP authentication credentials weren’t migrated correctly. In the cloud version, you need to use OAuth tokens instead of basic username/password authentication. Go to System Configuration > Notification Settings > SMTP Configuration and look for the ‘Authentication Method’ dropdown - it should be set to ‘OAuth 2.0’ not ‘Basic Auth’. You’ll also need to register your UKG instance as an authorized application in your email provider’s admin console if you’re using Microsoft 365 or Google Workspace.

6

Here’s the complete solution addressing all the components needed to restore your onboarding notifications:

SMTP Relay Configuration: The cloud environment uses dedicated relay servers that require explicit whitelisting. Your IT team needs to configure firewall rules to allow outbound connections to:

  • Primary: relay.ukgpro.cloud:587
  • Secondary: backup-relay.ukgpro.cloud:587 Both require TLS 1.2 or higher. The connection timeout errors you’re seeing indicate these endpoints were blocked at the network level.

Firewall Rules: Beyond basic whitelisting, ensure your firewall supports STARTTLS on port 587. Some enterprise firewalls have deep packet inspection that interferes with TLS negotiation. You may need to create an exception rule specifically for the UKG relay domains to bypass DPI. Also verify that your proxy server (if you use one) isn’t intercepting the TLS handshake.

Notification Template Validation: After fixing connectivity, validate each onboarding template:


Template: New_Hire_Welcome
Status: Active
Test Result: Merge fields validated
Sample Send: SUCCESS

Go to Onboarding > Configuration > Notification Templates and use the ‘Test Send’ function with a real employee ID to confirm templates render properly.

Third-Party Provider Authentication: This is the critical piece - UP 2022.2 cloud requires OAuth 2.0 for email provider integration, not basic authentication. Here’s the setup process:

  1. Azure AD Registration (for Microsoft 365):

    • Navigate to Azure Portal > Azure Active Directory > App Registrations
    • Create new registration: Name=‘UKG Pro Notifications’, Redirect URI=‘https://[your-instance].ukgpro.cloud/oauth/callback’
    • Generate client secret under Certificates & Secrets
    • Note the Application (client) ID and Directory (tenant) ID

  2. API Permissions:

    • In your app registration, go to API Permissions
    • Add ‘Microsoft Graph’ > Application permissions
    • Select ‘Mail.Send’ permission
    • Click ‘Grant admin consent’ (requires admin privileges)

  3. UKG Pro Configuration:

  4. DNS Configuration: Add SPF record to authorize UKG cloud servers:

    
v=spf1 include:_spf.ukgpro.cloud include:spf.protection.outlook.com ~all

    Add DKIM record provided by UKG support for your instance

After completing all four areas, test the complete flow by creating a test onboarding task for a dummy employee and verifying the notification is sent and received. Monitor the notification logs for 24 hours to ensure no intermittent failures occur. The combination of proper firewall configuration, OAuth authentication, and DNS validation should fully restore your onboarding notification functionality.

7

Don’t forget to validate your notification templates after fixing the SMTP issues. Cloud migration sometimes corrupts template variables or formatting. Go through each onboarding notification template and use the ‘Test Send’ function to verify they render correctly with actual employee data. I’ve seen cases where the SMTP connection works fine but templates have broken merge fields that prevent sending.