SMTP Setup¶

This guide explains how to configure SMTP for email notifications in the Traceable Platform.

Overview¶

SMTP (Simple Mail Transfer Protocol) configuration enables the Traceable Platform to send email notifications for alerts, user invitations, and other communications. The platform supports both standard SMTP servers and SendGrid.

Prerequisites¶

Before configuring SMTP, ensure you have:

Access to the Traceable Operator UI
SMTP server details (host, port, credentials) OR SendGrid API key
Email address to use as the sender

Configuration Steps¶

Navigate to your Traceable Operator URL and log in with your credentials.

2. Access Global Variables¶

Click on Global Variables in the sidebar menu
Click Show All to display all available variables

3. Configure SMTP Settings¶

Configure the following SMTP variables based on your email provider:

For Standard SMTP Server¶

smtpHost¶

Enter your SMTP server hostname (e.g., smtp.example.com)
For SendGrid: Enter N/A

smtpPort¶

Enter your SMTP server port (common ports: 25, 587, 465)
For SendGrid: Enter N/A

smtpUsername¶

Enter the username for SMTP authentication
Skip this field if no username is required (typically for on-prem SMTP servers)
For SendGrid: Enter your SendGrid username

For SendGrid or API-based Email¶

sendgridApiKey¶

Enter your SendGrid API Key or App Password
Important: Even if you don't need authentication for SMTP, make sure that sendgridApiKey is set to none or else notification-sender and iamv2 services will fail

4. Save Configuration¶

Click on the Save Values button to save your SMTP configuration.

5. Apply Secrets¶

Navigate to Install Workflow
Select add-secrets from the workflow list
Click on the Apply button

This step creates/updates the Kubernetes secrets with your SMTP credentials.

6. Configure Integration Service¶

6.1 Access Helm Releases¶

Click on Helm Releases in the sidebar menu.

6.2 Filter for Integration Service¶

Click Filter Helm Releases
Select the integration-service helm chart

6.3 Update Values¶

Click on user/values.yaml
Add the following configuration:

emailIntegrationServiceConfig:
  emailName: "Traceable"
  emailAddress: "no-reply@traceable.ai"

Note: Use the same email address as your smtpUsername if you are using SendGrid

Click Save All to save the changes

7. Verify and Apply Changes¶

7.1 Review Changes¶

Click HELM ACTIONS
Click on the Helm Diff button
Verify the changes shown in the diff output

7.2 Apply Changes¶

Click HELM UPGRADE
Click on the Helm Upgrade button to apply the changes

8. Wait for Service Restart¶

Wait for the integration service to restart. You can monitor the pod status:

kubectl get pods -n <traceable-namespace> -l app=integration-service -w

The pod should transition to Running state after the restart.

Configuration Examples¶

Example 1: SendGrid¶

emailIntegrationServiceConfig:
   emailName: "Traceable"
   emailAddress: "no-reply@traceable.ai"
   smtp:
      host: "smtp.sendgrid.net"
      port: 587
      username: "apikey"

Example 2: On-Prem SMTP (No Auth)¶

emailIntegrationServiceConfig:
   emailName: "Traceable"
   emailAddress: "noreply@company.com"
   smtp:
      host: "smtp.internal.company.com"
      port: 25

Verification¶

After configuration, verify SMTP is working:

1. Check Service Status¶

kubectl get pods -n <traceable-namespace> -l app=notification-sender
kubectl get pods -n <traceable-namespace> -l app=integration-service

Expected output:

NAME                                  READY   STATUS    RESTARTS   AGE
notification-sender-xxxxxxxxxx-xxxxx  1/1     Running   0          2m
integration-service-xxxxxxxxxx-xxxxx  1/1     Running   0          2m

2. Check Service Logs¶

kubectl logs -n <traceable-namespace> -l app=notification-sender --tail=50
kubectl logs -n <traceable-namespace> -l app=integration-service --tail=50

Look for successful SMTP connection messages and no authentication errors.

3. Send a Test Email via curl¶

curl natively supports SMTP and can be used to send a test email directly from your terminal or from within a Kubernetes debug pod, using the same parameters configured in the platform.

Variables¶

Replace the placeholders below with your actual values before running the commands:

Variable	Example value	Description
`SMTP_HOST`	`smtp.example.com`	Value of `smtpHost`
`SMTP_PORT`	`587`	Value of `smtpPort`
`SMTP_USER`	`user@example.com`	Value of `smtpUsername`
`SMTP_PASS`	`yourpassword`	Value of `sendgridApiKey` (or SMTP password)
`FROM_ADDR`	`noreply@example.com`	Value of `traceableEmailAddress`
`TO_ADDR`	`recipient@example.com`	Destination address for the test

Standard SMTP with STARTTLS (port 587)¶

curl --url "smtp://<SMTP_HOST>:<SMTP_PORT>" \
  --ssl-reqd \
  --user "<SMTP_USER>:<SMTP_PASS>" \
  --mail-from "<FROM_ADDR>" \
  --mail-rcpt "<TO_ADDR>" \
  --upload-file - <<EOF
From: <FROM_ADDR>
To: <TO_ADDR>
Subject: Traceable SMTP Test

This is a test email sent via curl to verify SMTP configuration.
EOF

SMTP with SSL/TLS (port 465)¶

curl --url "smtps://<SMTP_HOST>:465" \
  --user "<SMTP_USER>:<SMTP_PASS>" \
  --mail-from "<FROM_ADDR>" \
  --mail-rcpt "<TO_ADDR>" \
  --upload-file - <<EOF
From: <FROM_ADDR>
To: <TO_ADDR>
Subject: Traceable SMTP Test

This is a test email sent via curl to verify SMTP configuration.
EOF

On-Prem SMTP without authentication (port 25)¶

curl --url "smtp://<SMTP_HOST>:25" \
  --mail-from "<FROM_ADDR>" \
  --mail-rcpt "<TO_ADDR>" \
  --upload-file - <<EOF
From: <FROM_ADDR>
To: <TO_ADDR>
Subject: Traceable SMTP Test

This is a test email sent via curl to verify SMTP configuration.
EOF

Running the test from inside a Kubernetes pod¶

If your SMTP server is only reachable from within the cluster, run the test from a debug pod:

kubectl run -it --rm smtp-test --image=curlimages/curl --restart=Never -- \
  curl --url "smtp://<SMTP_HOST>:<SMTP_PORT>" \
  --ssl-reqd \
  --user "<SMTP_USER>:<SMTP_PASS>" \
  --mail-from "<FROM_ADDR>" \
  --mail-rcpt "<TO_ADDR>" \
  -T - <<EOF
From: <FROM_ADDR>
To: <TO_ADDR>
Subject: Traceable SMTP Test

This is a test email sent via curl to verify SMTP configuration.
EOF

A successful response will show a 250 status code from the SMTP server. If you see authentication or connection errors, refer to the Troubleshooting section below.

4. Test Email Notification¶

Login to the Traceable UI
Navigate to Settings → Notifications
Create a test notification or invite a user
Verify the email is received

Troubleshooting¶

Issue: notification-sender or iamv2 Fails to Start¶

Cause: sendgridApiKey is not set when using SMTP without authentication.

Solution: Set sendgridApiKey to none in Global Variables and reapply the configuration.

Issue: Authentication Failed¶

Symptoms: Logs show authentication errors

Solutions:

Verify smtpUsername and sendgridApiKey are correct
For Gmail, ensure you're using an App Password, not your regular password
Check if your SMTP server requires TLS/SSL
Verify firewall rules allow outbound connections to SMTP server

Issue: Connection Timeout¶

Symptoms: Cannot connect to SMTP server

Solutions:

Verify smtpHost and smtpPort are correct
Check network connectivity from Kubernetes pods to SMTP server:

kubectl run -it --rm debug --image=nicolaka/netshoot --restart=Never -- nc -zv smtp.example.com 587

Verify firewall rules allow outbound SMTP traffic
Check if SMTP server requires whitelisting of IP addresses

Issue: Emails Not Received¶

Symptoms: No errors in logs but emails not received

Solutions:

Check spam/junk folders
Verify traceableEmailAddress is correct and authorized to send
Check SMTP server logs for delivery issues
Verify recipient email addresses are valid
Check email quotas and rate limits

Issue: TLS/SSL Certificate Errors¶

Symptoms: Certificate validation errors in logs

Solutions:

Verify SMTP server certificate is valid
If using self-signed certificates, you may need to configure trust
Check if the correct port is being used (587 for STARTTLS, 465 for SSL/TLS)

Security Best Practices¶

Use App Passwords: For services like Gmail, always use app-specific passwords
Secure Credentials: SMTP credentials are stored as Kubernetes secrets
TLS/SSL: Always use encrypted connections (ports 587 or 465)
Least Privilege: Use dedicated email accounts with minimal permissions
Rotate Credentials: Regularly rotate SMTP passwords and API keys
Monitor Usage: Monitor email sending patterns for anomalies

Support¶

For SMTP configuration assistance or issues, contact: support@harness.io

Provide the following information when requesting support:

SMTP provider (Gmail, SendGrid, on-prem, etc.)
Error messages from notification-sender logs
Network connectivity test results
Helm diff output

SMTP Setup¶

Overview¶

Prerequisites¶

Configuration Steps¶

1. Login to Traceable Operator¶

2. Access Global Variables¶

3. Configure SMTP Settings¶

For Standard SMTP Server¶

smtpHost¶

smtpPort¶

smtpUsername¶

For SendGrid or API-based Email¶

sendgridApiKey¶

4. Save Configuration¶

5. Apply Secrets¶

6. Configure Integration Service¶

6.1 Access Helm Releases¶

6.2 Filter for Integration Service¶

6.3 Update Values¶

7. Verify and Apply Changes¶

7.1 Review Changes¶

7.2 Apply Changes¶

8. Wait for Service Restart¶

Configuration Examples¶

Example 1: SendGrid¶

Example 2: On-Prem SMTP (No Auth)¶

Verification¶

1. Check Service Status¶

2. Check Service Logs¶

3. Send a Test Email via curl¶

Variables¶

Standard SMTP with STARTTLS (port 587)¶

SMTP with SSL/TLS (port 465)¶

On-Prem SMTP without authentication (port 25)¶

Running the test from inside a Kubernetes pod¶

4. Test Email Notification¶

Troubleshooting¶

Issue: notification-sender or iamv2 Fails to Start¶

Issue: Authentication Failed¶

Issue: Connection Timeout¶

Issue: Emails Not Received¶

Issue: TLS/SSL Certificate Errors¶

Security Best Practices¶

Support¶