dmail-api/EMAIL_BLOCKING_DIAGNOSTIC.md

Email Blocking Diagnostic Tool

This document explains how to diagnose and fix email blocking issues in the d-mail system.

Problem

A client (r.sadat@humapek.co) cannot receive emails from russel.s@metixco.ae, but can receive emails from other senders.

Solution

A diagnostic endpoint has been added to check if a sender domain is blocked and optionally unblock it.

Usage

Check if a domain is blocked (Diagnostic Mode)

GET /email/diagnose-blocking?recipient=r.sadat@humapek.co&senderDomain=metixco.ae

Response:

{
  "recipientEmail": "r.sadat@humapek.co",
  "senderDomain": "metixco.ae",
  "user": {
    "id": "user-id",
    "email": "r.sadat@humapek.co",
    "wildduckUserId": "wildduck-user-id",
    "businessId": "business-id"
  },
  "domainTag": "business-id",
  "blocked": true,
  "blockedDomains": [
    {
      "domain": "metixco.ae",
      "description": "Auto-blocked due to spam report",
      "created": "2024-01-01T00:00:00Z"
    }
  ],
  "blockingFilters": [],
  "message": "Domain metixco.ae is blocked. Use unblock=true to unblock it."
}

Unblock a domain

GET /email/diagnose-blocking?recipient=r.sadat@humapek.co&senderDomain=metixco.ae&unblock=true

Response:

{
  "recipientEmail": "r.sadat@humapek.co",
  "senderDomain": "metixco.ae",
  "user": { ... },
  "domainTag": "business-id",
  "blocked": false,
  "unblocked": true,
  "message": "Domain metixco.ae has been unblocked successfully"
}

Authentication

This endpoint requires Admin authentication. Make sure you're authenticated as an admin user.

How It Works

1. Finds the recipient user by email address
2. Determines the domain tag (usually the business ID, or "default")
3. Checks blocked domains for that domain tag
4. Checks email filters that might be blocking emails from the sender domain
5. Optionally unblocks the domain if requested

Common Causes

1. Domain Blocking: The sender domain was marked as spam and automatically blocked
2. Email Filters: User-created filters that delete or mark as spam emails from specific domains
3. WildDuck Configuration: Server-level blocking (less common)

Troubleshooting

If the domain is not blocked but emails still aren't arriving:

Step 1: Check WildDuck Server Logs

Look for SMTP rejection messages, connection attempts, or errors related to the sender domain:

# Check WildDuck logs for SMTP rejections
grep -i "metixco.ae" /var/log/wildduck/*.log
grep -i "r.sadat@humapek.co" /var/log/wildduck/*.log

Step 2: Verify DNS/MX Records

Check that the recipient domain has correct MX records:

dig MX humapek.co
nslookup -type=MX humapek.co

Step 3: Check Sender's Email Server

Ask the sender to:

• Check their email server logs for delivery attempts
• Look for bounce messages or error codes
• Verify the email address is correct: r.sadat@humapek.co

Step 4: Verify SPF/DKIM/DMARC Records

Check email authentication records:

# Check SPF record for sender domain
dig TXT metixco.ae | grep -i spf

# Check DMARC record
dig TXT _dmarc.metixco.ae

Step 5: Test with Allowlist

Try adding the domain to allowlist as a test:

POST /email-blocking/allowlist
{
  "recipientEmail": "r.sadat@humapek.co",
  "senderDomain": "metixco.ae",
  "description": "Test allowlist for troubleshooting"
}

Step 6: Check Firewall/Network

• Verify sender's IP is not blocked by firewall
• Check if there are any network-level restrictions
• Ensure SMTP port (usually 25, 587, or 465) is open

Example: Fix the Current Issue

To fix the issue with r.sadat@humapek.co not receiving emails from russel.s@metixco.ae:

# First, check the status
curl -X GET "http://your-api-url/email/diagnose-blocking?recipient=r.sadat@humapek.co&senderDomain=metixco.ae" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# If blocked, unblock it
curl -X GET "http://your-api-url/email/diagnose-blocking?recipient=r.sadat@humapek.co&senderDomain=metixco.ae&unblock=true" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Notes

• The domain tag is typically the business ID of the recipient user
• If a user doesn't have a business, the domain tag defaults to "default"
• Unblocking a domain affects all users in the same business (same domain tag)
• The diagnostic also checks for email filters that might be blocking emails