title: Troubleshooting Email Delivery category: Troubleshooting tags: troubleshooting, email, smtp, tls, delivery, notifications priority: Normal

Troubleshooting Email Delivery

This guide helps you diagnose and resolve email delivery failures in IdentityCenter. Email notifications are critical for access reviews, policy violations, workflow approvals, and system alerts.

Common SMTP Errors and Solutions

Authentication Failed

Error: 535 5.7.8 Authentication credentials invalid or Authentication failed

Solutions:

1. Verify the username and password in email settings are correct
2. Check that the account is not locked or disabled
3. For Microsoft 365, ensure the account has an active mailbox license
4. If using Basic authentication with Microsoft 365, confirm that Basic auth is not blocked by a Conditional Access policy
5. For OAuth 2.0, verify the client ID, tenant ID, and client secret are current

Connection Refused

Error: Unable to connect to the remote server or Connection refused

Solutions:

1. Verify the SMTP server address is correct (no typos)
2. Check that the port number matches the server's configuration
3. Test firewall connectivity from the IdentityCenter server:

   Test-NetConnection -ComputerName smtp.office365.com -Port 587
   

4. Ensure outbound SMTP traffic is allowed through your firewall
5. Check if your hosting provider blocks outbound SMTP (common on cloud VMs)

TLS Handshake Failure

Error: The handshake failed due to an unexpected packet format or SSL/TLS error

Solutions:

1. Verify you are using the correct port for your TLS mode:

   TLS Mode	Port	Behavior
   StartTLS	587	Connects plain, upgrades to TLS
   Implicit SSL	465	Connects directly over SSL
   None	25	No encryption (not recommended)

2. Ensure TLS 1.2 is enabled on the IdentityCenter server

3. If the SMTP server uses a self-signed certificate, import it into the server's trusted store

4. Try switching between port 587 (StartTLS) and port 465 (Implicit SSL)

Relay Denied

Error: 550 5.7.1 Unable to relay or Relay access denied

Solutions:

1. Verify the "From" address domain is authorized on the SMTP server
2. For Exchange Server, ensure the connector allows relay from the IdentityCenter server's IP
3. For Microsoft 365, ensure the authenticated account has a mailbox or is authorized to send as the "From" address
4. Check if the SMTP server requires authentication before relaying

Testing Email: The SMTP Test Page

IdentityCenter provides a built-in SMTP test tool at /admin/smtp-test:

1. Navigate to Administration > SMTP Test
2. Enter a recipient email address
3. Click Send Test Email
4. Review the results

Test result interpretation:

Configuration Checklist

Verify each setting before troubleshooting further:

Provider-Specific Setup

Microsoft 365

Option 1: OAuth 2.0 (Recommended)

1. Register an application in Azure AD (Entra ID)

2. Grant the Mail.Send permission (application type)

3. Create a client secret or certificate

4. Configure in IdentityCenter:

   Setting	Value
   Server	smtp.office365.com
   Port	587
   TLS Mode	StartTLS
   Auth Type	OAuth 2.0
   Tenant ID	Your Azure AD tenant ID
   Client ID	Application (client) ID
   Client Secret	Your client secret

Option 2: App Password (if MFA is enabled)

1. Sign in to the Microsoft account security page
2. Generate an app password under Security > Additional Security > App Passwords
3. Use the generated password instead of the account password in IdentityCenter

Exchange Server (On-Premises)

1. Create a receive connector on the Exchange server that allows relay from the IdentityCenter server's IP address

2. Configure in IdentityCenter:

   Setting	Value
   Server	mail.company.com (your Exchange server)
   Port	587 or 25
   TLS Mode	StartTLS (if certificates are configured)
   Auth Type	Basic (NTLM)
   Username	DOMAIN\svc-identity

3. If using anonymous relay, set Auth Type to None and ensure the receive connector permits the source IP

Gmail / Google Workspace

1. App passwords are required if 2-Step Verification is enabled

2. Generate an app password at Google Account > Security > App passwords

3. Configure in IdentityCenter:

   Setting	Value
   Server	smtp.gmail.com
   Port	587
   TLS Mode	StartTLS
   Auth Type	Basic
   Username	your-account@company.com
   Password	App-specific password

Note: Google may block sign-in attempts from IdentityCenter if it considers the location or device unfamiliar. Check the Google Admin console for blocked sign-in alerts.

Email Queue

How the Queue Works

IdentityCenter queues outgoing emails and processes them via the EmailQueueProcessingJob. This Quartz.NET job:

• Picks up queued emails in order
• Attempts delivery with automatic retry on transient failures
• Marks emails as failed after exceeding the maximum retry count

Monitoring the Queue

1. Navigate to /admin/processing-center to view queued email jobs
2. Check for backed-up emails that indicate a persistent delivery problem
3. Review failed emails in the application logs for specific error messages

Queue Stalled

If emails are stuck in the queue:

1. Verify the EmailQueueProcessingJob is scheduled and running (check Administration > Jobs)
2. Check application logs for errors from the email processing service
3. Test SMTP connectivity using the SMTP Test page
4. Restart the job from Processing Center if needed

Rate Limiting

Sending Too Many Emails Too Fast

Symptoms:

• Some emails delivered, others fail with "too many connections" or "rate limit exceeded"
• Intermittent 421 or 450 SMTP response codes

Solutions:

1. Configure rate limiting in email settings to respect your SMTP provider's limits:

   Provider	Typical Limit	Recommended Setting
   Microsoft 365	30 messages/minute	25 messages/minute
   Exchange Server	Varies by configuration	Match your connector limits
   Gmail	500/day (free), 2000/day (Workspace)	Stay well under the cap
   Generic SMTP	Varies	Check provider documentation

2. Use batch sending for large notification runs (access review campaigns)

3. Space out scheduled notifications to avoid bursts

Notification Not Received

When a specific recipient reports missing emails:

1. Check the spam/junk folder -- The most common cause of missing notifications
2. Verify the recipient address -- Check for typos in the user's email field
3. Check the email logs at /admin/logging -- Filter for the recipient address to see if delivery was attempted
4. Verify the notification is enabled -- Some notification types can be disabled per user or globally
5. Check email rules -- The recipient's mailbox rules may be redirecting or deleting the message
6. DNS records -- Ensure your sending domain has valid SPF, DKIM, and DMARC records to avoid spam filtering

Improving Deliverability

Best Practices

1. Use a dedicated service account -- Do not use a personal email account for application notifications
2. Enable TLS -- Always encrypt SMTP connections in production
3. Monitor delivery rates -- Review email logs weekly for failed deliveries
4. Set a recognizable From address -- Use something like identitycenter@company.com so recipients recognize the sender
5. Test after any change -- Use the SMTP Test page after modifying any email configuration
6. Rotate credentials -- Update the SMTP password periodically and verify delivery still works

Next Steps

• Email Configuration
• Creating Email Templates
• Email Template Variables Reference
• Log Analysis & Diagnostics
• Common Issues & Solutions