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)

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

**Response:**
```json
{
  "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

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

**Response:**
```json
{
  "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:
```bash
# 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:
```bash
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:
```bash
# 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:
```bash
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`:

```bash
# 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