SMTP Troubleshooting

Common issues and solutions for SMTP integration.

Authentication Failed

Symptoms: "Authentication failed" or "Invalid credentials" errors

Solutions:

• Verify motor block username and password are correct
• Check for extra spaces or hidden characters in credentials
• Ensure motor block status is "active" in the dashboard
• If using API key, verify the key hasn't been revoked
• For OAuth, ensure tokens haven't expired

Connection Timeout

Symptoms: "Connection timed out" or "Could not connect to server" errors

Solutions:

• Check firewall allows outbound connections on port 2587 (or 587)
• Verify server hostname: mail.motorical.com
• Test DNS resolution: nslookup mail.motorical.com
• Try alternative port 587 if 2587 is blocked
• Check if your ISP blocks SMTP ports

# Test connectivity
telnet mail.motorical.com 2587

# If that fails, try:
telnet mail.motorical.com 587

TLS/SSL Issues

Symptoms: "TLS negotiation failed", "SSL/TLS handshake error", or "Certificate errors"

Solutions:

• Enable STARTTLS in your SMTP client configuration
• Verify TLS version compatibility (TLS 1.2+ required)
• Update your system's CA certificate bundle
• Check system clock accuracy (must be within ±5 minutes)
• Verify certificate chain completeness

# Test TLS connection
openssl s_client -connect mail.motorical.com:587 -starttls smtp -crlf

# Check certificate
echo | openssl s_client -connect mail.motorical.com:587 \
  -starttls smtp 2>/dev/null | openssl x509 -noout -dates

Emails Not Delivering

Symptoms: Emails are accepted by the server but don't arrive at the destination

Solutions:

1. Check delivery logs in the Motorical dashboard
2. Verify SPF, DKIM, and DMARC DNS records are correctly configured
3. Check the Motor Block's domain health status
4. Look for bounce notifications in your Motor Block's event stream
5. Verify the recipient address is valid

Rate Limiting

Symptoms: "Too many connections" or emails being queued/delayed

Solutions:

• Check your plan's sending limits in the dashboard
• Implement sending delays between batch emails
• Monitor rate limit headers from the API
• Consider upgrading your plan for higher limits

Email Formatting Issues

Symptoms: Emails arrive with broken formatting or encoding issues

Solutions:

• Set Content-Type: text/html; charset=utf-8 for HTML emails
• Always include a plain-text alternative
• Test with multiple email clients (Gmail, Outlook, Apple Mail)
• Validate HTML with an email preview tool

Error Reference

Error Code	Meaning	Action
535	Authentication failed	Check credentials
550	Recipient rejected	Verify recipient address
421	Service temporarily unavailable	Retry with backoff
452	Insufficient storage	Check plan limits
554	Transaction failed	Check message content/headers

Getting Help

If you're still experiencing issues:

• Email: [email protected]
• Include your error details, motor block ID, and timestamps
• Check status.motorical.com for service issues