How to Use SendSMTP: A Beginner’s Guide to Sending Email Programmatically

Troubleshooting SendSMTP: Common Errors and Fixes

1. Unable to connect to SMTP server

• Cause: Wrong host/port, server down, or network/Firewall blocking.
• Fixes:
  1. Verify host and port: Confirm SMTP hostname and port (25, 587, 465 commonly).
  2. Test connectivity: Run telnet smtp.example.com 587 or openssl s_client -connect smtp.example.com:465 to check reachability.
  3. Check firewall/NAT: Allow outbound traffic on the SMTP port; if running in cloud, check security group rules.
  4. Use correct protocol: Port 465 expects SMTPS (implicit TLS); 587 expects STARTTLS (explicit TLS).

2. Authentication failed (535 / 5.7.8 / Invalid credentials)

• Cause: Incorrect username/password, account locked, or authentication method mismatch.
• Fixes:
  1. Confirm credentials: Re-enter username and password; try logging into the provider’s web portal.
  2. Check auth method: Ensure SendSMTP is configured for the provider’s required auth (PLAIN, LOGIN, or OAuth2).
  3. Account security: Verify account isn’t locked or requiring CAPTCHA/2FA. For accounts with 2FA, create and use an app-specific password or OAuth2 token.
  4. Rate limits: Ensure you haven’t hit provider rate limits which can appear as auth errors.

3. TLS/SSL errors (certificate validation failures)

• Cause: Expired/invalid server certificate, missing CA bundle, or hostname mismatch.
• Fixes:
  1. Inspect certificate: Use openssl s_client -connect to view the certificate chain and expiry.
  2. Update CA store: Ensure the runtime has an up-to-date CA certificate bundle.
  3. Hostname verification: Confirm the SMTP hostname matches the certificate common name/SAN.
  4. Temporary workaround: For testing only, disable strict certificate verification — do not use in production.

4. Emails marked as spam or rejected (550 / 554)

• Cause: Missing SPF/DKIM/DMARC, poor sender reputation, blacklisted IP, or suspicious content.
• Fixes:
  1. Publish SPF: Add an SPF record authorizing your sending servers.
  2. Set up DKIM: Sign outgoing messages with DKIM and publish the public key DNS record.
  3. Implement DMARC: Add a DMARC policy to help receivers handle unauthenticated mail.
  4. Check content: Avoid spammy phrases, excessive links, and suspicious attachments.
  5. IP reputation: Check if your sending IP is blacklisted and request delisting if needed.

5. Message queueing or delayed delivery

• Cause: Provider throttling, transient network issues, large attachment sizes, or high send volume.
• Fixes:
  1. Monitor bounce and defer logs: Identify patterns or throttle responses from the server.
  2. Retry strategy: Implement exponential backoff with capped retries.
  3. Optimize payload: Reduce attachment sizes or host large files externally.
  4. Rate limits: Respect provider send limits; consider batching or upgrading plan.

6. Bounces and non-delivery receipts (NDRs)

• Cause: Invalid recipient address, recipient server policy, mailbox full, or mailbox disabled.
• Fixes:
  1. Parse bounce codes: Use the SMTP/NDR code and diagnostic text to determine cause.
  2. Validate addresses: Remove or flag permanently bounced addresses from lists.
  3. Retry soft bounces: For transient