Troubleshooting Guide

This guide covers common issues and their solutions.

📧 Email Delivery Issues

Emails Not Sending

Symptoms: Emails stuck in queue or showing failed status

Check SMTP Configuration:

# Test SMTP connection
telnet smtp.your-server.com 587

# Test with SSL
openssl s_client -connect smtp.your-server.com:465

Common Fixes:

1. ✅ Verify SMTP credentials (username/password)
2. ✅ Check SMTP server address and port
3. ✅ Confirm encryption method (TLS/SSL)
4. ✅ Ensure firewall allows SMTP ports
5. ✅ Check ISP doesn't block SMTP

High Bounce Rate

Symptoms: Bounce rate exceeds 5%

Soft Bounces (Temporary):

• Mailbox full → Auto-retry
• Server temporarily unavailable → Wait

Hard Bounces (Permanent):

• Invalid email address → Remove from list
• Domain doesn't exist → Remove immediately
• Rejected by recipient → Check content

Prevention:

• Use double opt-in
• Clean list regularly
• Validate emails on import

🔗 API Issues

API Request Errors

400 Bad Request:

// Common cause: Invalid request format
// Solution: Check request body
const response = await fetch('https://api.maildrone.com/v2/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',  // Ensure valid format
    first_name: 'John'
  })
});

401 Unauthorized:

• Check API key format
• Verify key permissions
• Ensure key is active

429 Rate Limited:

// Implement retry with backoff
async function retryRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429) {
      const delay = Math.pow(2, i) * 1000;
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    return response;
  }
}

Webhook Issues

Events Not Received:

1. Check Endpoint:

   curl -X POST https://your-server.com/webhook \
        -H "Content-Type: application/json" \
        -d '{"test": true}'
   # Should return 200

2. Verify SSL:

   • Certificate must be valid
   • Use HTTPS only

3. Check Signature:

   const crypto = require('crypto');
   
   function verifySignature(payload, signature, secret) {
     const expected = crypto
       .createHmac('sha256', secret)
       .update(payload)
       .digest('hex');
     return signature === `sha256=${expected}`;
   }

🎨 Template Issues

Template Not Saving

Quick Fixes:

1. 📋 Copy content to clipboard
2. 🔄 Refresh page and re-login
3. 📝 Paste content and save
4. ✅ Confirm save success

Common Causes:

• Browser storage full → Clear cache
• Network interruption → Check connection
• Content too large → Optimize images

Variables Not Replacing

Correct Syntax:

<!-- ✅ Correct -->
<h1>Hi {{first_name}}!</h1>

<!-- ❌ Wrong -->
<h1>Hi {first_name}!</h1>     <!-- Single braces -->
<h1>Hi {{ first_name }}!</h1> <!-- Spaces inside -->

Debug Steps:

1. Use template tester
2. Check variable names match data
3. Verify data format

📊 Analytics Issues

Inaccurate Statistics

Open Tracking Check:

<!-- Ensure tracking pixel exists -->
<img src="https://track.maildrone.com/o/..." 
     width="1" height="1" style="display:none;">

Click Tracking Test:

# Original link should redirect
curl -I "https://track.maildrone.com/c/abc123..."
# Should return 302 redirect

Common Issues:

Reports Not Exporting

Browser Check:

• Update to latest version
• Try Chrome, Firefox, or Safari
• Check download settings
• Disable download-blocking extensions

⚙️ Configuration Issues

DNS Settings

SPF Record:

# Check SPF
dig TXT yourdomain.com | grep spf

# Correct format
"v=spf1 include:_spf.maildrone.com ~all"

DKIM Record:

# Check DKIM
dig TXT selector._domainkey.yourdomain.com

DMARC Record:

# Check DMARC
dig TXT _dmarc.yourdomain.com

# Recommended stages:
# Stage 1: p=none (monitoring)
# Stage 2: p=quarantine (soft enforcement)
# Stage 3: p=reject (strict enforcement)

SMTP Connection

Test Connection:

# Basic test
telnet smtp.server.com 587

# SSL test
openssl s_client -connect smtp.server.com:465

Checklist:

• ✅ Server address correct
• ✅ Port correct (587/465/25)
• ✅ Encryption matches (STARTTLS/SSL)
• ✅ Credentials correct
• ✅ Firewall allows port

🚀 Performance Issues

Slow Page Loading

Quick Fixes:

1. 🌐 Use faster DNS (8.8.8.8, 1.1.1.1)
2. 🔄 Clear browser cache
3. 📡 Check internet connection
4. 🖥️ Disable unused browser extensions

Test CDN:

curl -w "Connect: %{time_connect} Total: %{time_total}\n" \
     -o /dev/null -s https://cdn.maildrone.com/app.js

Slow Bulk Operations

Batch Processing:

// Process in batches
async function batchImport(contacts) {
  const batchSize = 1000;
  for (let i = 0; i < contacts.length; i += batchSize) {
    const batch = contacts.slice(i, i + batchSize);
    await importBatch(batch);
    await new Promise(r => setTimeout(r, 5000)); // Wait between batches
  }
}

📞 Getting Help

What to Include in Support Requests

1. 🔍 Detailed description - What happened, when
2. 📷 Screenshots - Show the error
3. 🌐 Browser info - Version and OS
4. 📋 Error messages - Exact text
5. 🔄 Steps to reproduce - How to recreate

Support Channels

Urgent Issues:

• 📧 [email protected]
• 📞 Emergency hotline (Enterprise)
• 💬 Live chat

Non-Urgent:

• Submit ticket in app
• Community forum
• Documentation

We're committed to helping you resolve any issues quickly. Don't hesitate to reach out!