{"record":{"id":"a89ef175ded44041","repo":"Billionmail/BillionMail","slug":"failed-to-connect-to-smtp-server-v","errorCode":null,"errorMessage":"failed to connect to SMTP server: %v","messagePattern":"failed to connect to SMTP server: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/internal/controller/settings/settings_v1_set_blacklist_alert_settings.go","lineNumber":133,"sourceCode":"\treturn nil\n}\n\nfunc sendTestEmailWithMailService(ctx context.Context, settings *v1.SetBlacklistAlertSettingsReq) error {\n\t//g.Log().Infof(ctx, \"Sending test email to %v\", settings.RecipientList)\n\n\tsubject := \"Blacklist Alert Test - BillionMail\"\n\tbody := buildTestEmailHTML(settings)\n\n\tsender := mail_service.NewEmailSender()\n\tsender.Host = settings.SMTPServer\n\tsender.Port = fmt.Sprintf(\"%d\", settings.SMTPPort)\n\tsender.Email = settings.SenderEmail\n\tsender.UserName = settings.SenderEmail\n\tsender.Password = settings.SMTPPassword\n\n\terr := sender.Connect()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to connect to SMTP server: %v\", err)\n\t}\n\tdefer sender.Close()\n\n\tvar failedRecipients []string\n\tfor _, recipient := range settings.RecipientList {\n\n\t\tmessage := mail_service.NewMessage(subject, body)\n\t\tmessage.SetRealName(settings.Name)\n\t\tmessageId := sender.GenerateMessageID()\n\t\tmessage.SetMessageID(messageId)\n\n\t\terr = sender.Send(message, []string{recipient})\n\t\tif err != nil {\n\t\t\tg.Log().Errorf(ctx, \"Failed to send test email to %s: %v\", recipient, err)\n\t\t\tfailedRecipients = append(failedRecipients, recipient)\n\t\t} else {\n\t\t\tg.Log().Infof(ctx, \"Test email sent successfully to %s\", recipient)\n\t\t}","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/Billionmail/BillionMail/blob/fc36c76c050c3775c5e899faf7403cf0262d2744/core/internal/controller/settings/settings_v1_set_blacklist_alert_settings.go#L115-L151","documentation":"sendTestEmailWithMailService builds an SMTP sender from the submitted settings and calls sender.Connect(); any connection error is wrapped as 'failed to connect to SMTP server'. This happens before any email is sent — it is a TCP/TLS/handshake-level failure.","triggerScenarios":"SetBlacklistAlertSettings (non-relay test path) where sender.Connect() fails: wrong SMTPServer host, wrong SMTPPort, server unreachable, TLS handshake failure, or auth rejection at connect time.","commonSituations":"Firewall/egress rules block the port; DNS cannot resolve the host; server expects implicit TLS on 465 but code uses STARTTLS on 587 (or vice versa); credentials wrong so the server drops the session.","solutions":["Inspect the wrapped %v error for the root cause (dial timeout, refoused, x509, auth).","Confirm host:port with telnet/openssl s_client from the server running BillionMail.","Match the port to the encryption mode (465 = implicit TLS, 587 = STARTTLS).","If sending via the local mail service, point SMTPServer at the internal hostname (e.g. the mail container) instead of an external relay."],"exampleFix":"// before\n{\"smtpServer\":\"smtp.example.com\",\"smtpPort\":25} // blocked by provider\n// after\n{\"smtpServer\":\"smtp.example.com\",\"smtpPort\":587}","handlingStrategy":"retry","validationCode":"// dial check before saving\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(smtpServer, strconv.Itoa(smtpPort)), 5*time.Second)\nif err != nil { return fmt.Errorf(\"SMTP server unreachable: %w\", err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"if err := SetBlacklistAlertSettings(ctx, req); err != nil {\n  var netErr net.Error\n  if errors.As(err, &netErr) || strings.Contains(err.Error(), \"failed to connect\") {\n    // transient? retry with backoff; otherwise surface host/port guidance\n  }\n}","preventionTips":["Match port to TLS mode: 465 implicit TLS, 587 STARTTLS","Open firewall egress for the SMTP port from the app server","Use resolvable internal hostnames when relaying via the local mail service","Verify credentials with openssl s_client before saving settings"],"tags":["smtp","network","connection"],"backgroundTag":"smtp-connection-refused","analyzedSha":"fc36c76c050c3775c5e899faf7403cf0262d2744","analyzedAt":"2026-09-05T21:28:54.019Z","contentChangedAt":"2026-09-05T21:28:54.019Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}