Getting Started with MailSystem.NET: Setup, Sending, and Receiving Email

Troubleshooting MailSystem.NET: Common Errors and Fixes

1. SMTP connection failures

• Symptom: Exceptions like SmtpException, timeout, or “Unable to connect to remote server”.
• Causes: Wrong host/port, firewall/antivirus blocking, TLS/SSL mismatch, network issues, SMTP server requiring auth.
• Fixes:
  1. Verify SMTP host and port (e.g., 25, 465 for SSL, 587 for STARTTLS).
  2. Ensure EnableSsl or StartTls setting matches server. Try toggling if unsure.
  3. Confirm credentials and authentication method. Use NetworkCredential with correct username/password.
  4. Test connectivity with telnet or openssl: telnet smtp.example.com 587 or openssl s_client -starttls smtp -crlf -connect smtp.example.com:587.
  5. Check local firewall/antivirus and server-side IP blocks (rate limits, whitelisting).
  6. Increase client timeout if large attachments slow the handshake.

2. Authentication errors

• Symptom: ⁄₅₃₀ authentication failed, invalid credentials.
• Causes: Wrong username/password, account requires OAuth2 or app-specific password, two-factor auth, insecure auth disabled.
• Fixes:
  1. Re-enter credentials; verify by logging in with same credentials on webmail.
  2. If provider uses OAuth2 (Google, Microsoft), switch to an OAuth flow or use app password per provider docs.
  3. Ensure UseDefaultCredentials is false when supplying explicit credentials.
  4. Check for account lockouts or security alerts on provider side.

3. TLS/SSL and certificate problems

• Symptom: SslPolicyErrors, remote certificate validation exceptions, handshake failures.
• Causes: Self-signed or expired certificate, hostname mismatch, client expects TLS version not supported by server.
• Fixes:
  1. Update server certificate or use a CA-signed certificate.
  2. Ensure server hostname matches certificate CN/SAN.
  3. Allow required TLS versions in .NET (ServicePointManager.SecurityProtocol or SslProtocols when using newer APIs).
  4. For testing only, temporarily bypass validation (not recommended in production):
     ServicePointManager.ServerCertificateValidationCallback = (s, cert, chain, err) => true;

  5. Check for TLS 1.0/1.1 deprecation; enable TLS 1.2+ as required.

4. Message formatting and encoding issues

• Symptom: Garbled characters, wrong MIME boundaries, attachments corrupted.
• Causes: Incorrect Content-Type/charset, wrong transfer encoding, misbuilt MIME parts.
• Fixes:
  1. Set correct Encoding for Subject and Body (e.g., UTF8): mail.SubjectEncoding = Encoding.UTF8; mail.BodyEncoding = Encoding.UTF8;
  2. Use proper IsBodyHtml flag for HTML bodies.
  3. For attachments, set ContentType and ContentDisposition correctly and use streams rather than raw strings.
  4. Let the library build MIME parts rather than concatenating raw headers/bodies.

5. Large attachments / memory issues

• Symptom: OutOfMemoryException, high memory usage, slow send.
• Causes: Loading entire attachments into memory, using large in-memory strings.
• Fixes:
  1. Stream attachments from disk or use FileStream-backed Attachment objects.
  2. Set SmtpClient.ClientCertificates and other large objects carefully.
  3. Consider chunking large files or using a file-transfer link instead of embedding very large files.

6. Emails marked as spam or not delivered

• Symptom: Messages land in spam or bounce without clear SMTP error.
• Causes: Missing/incorrect SPF, DKIM, DMARC; poor sender reputation; malformed headers; lack of reverse DNS.
• Fixes:
  1. Publish SPF record authorizing your sending IPs.
  2. Sign outgoing mail with DKIM and set a DMARC policy.
  3. Ensure HELO/EHLO identifies your domain and reverse DNS matches.
  4. Avoid spammy content, proper MIME structure, and include List-Unsubscribe for bulk mail.
  5. Monitor bounces and complaints; request IP/domain delisting if blacklisted.

7. Multipart/alternate rendering problems

• Symptom: Clients show raw HTML or only plain text; inline images missing.
• Causes: Wrong multipart/alternate or related ordering; incorrect Content-IDs.
• Fixes:
  1. Create AlternateView objects for plain text and HTML; add HTML AlternateView after plain text.
  2. For inline images, set ContentId and reference with cid: in the HTML.
  3. Ensure ContentType.MediaType and CharSet are set correctly.

8. Threading and async issues

• Symptom: Deadlocks, exceptions when sending from background threads, SmtpClient not thread-safe.
• Causes: SmtpClient legacy API not thread-safe; improper async usage.