Skip to main content

​
SMTP Integration Guide

Connect your own SMTP server to send emails directly from Heffl. This guide covers setup, configuration options, troubleshooting, and best practices.

​
Overview

SMTP (Simple Mail Transfer Protocol) integration allows you to send emails using your own email server instead of Heffl’s default email service. This gives you:
  • Full control over your email sending domain and reputation
  • Custom sender addresses using your business domain
  • Higher sending limits based on your email provider
  • Better deliverability with properly configured SPF/DKIM/DMARC

​
Prerequisites

Before setting up SMTP integration, you’ll need:
  1. SMTP server credentials from your email provider
  2. Sender email address that’s authorized to send from your SMTP server
  3. DNS records configured (SPF, DKIM, DMARC) for optimal deliverability

​
Configuration Fields

​
Sender Email

The email address that will appear in the “From” field of sent emails.
  • Required: Yes
  • Example: [email protected]
  • Important: This must match your SMTP account or be an authorized alias. Using an unauthorized address may cause emails to be rejected.

​
From Name

The display name shown to recipients alongside the email address.
  • Required: No
  • Example: John from Acme Corp
  • Note: If left empty, recipients will only see the email address.

​
SMTP Host

Your email provider’s SMTP server address.
  • Required: Yes
  • Examples:
    • Gmail: smtp.gmail.com
    • Microsoft 365: smtp.office365.com
    • Zoho: smtp.zoho.com
    • Amazon SES: email-smtp.us-east-1.amazonaws.com
    • Custom hosting: Check your hosting provider’s documentation

​
Port

The port number used for SMTP connections.
  • Required: Yes
  • Common ports:
    PortEncryptionDescription
    587STARTTLSRecommended. Starts unencrypted, upgrades to TLS
    465SSL/TLSImmediate encryption (implicit TLS)
    25NoneUnencrypted. Often blocked by ISPs. Avoid if possible

​
Encryption

The security protocol used to encrypt the connection.
  • Required: Yes
  • Options:
    • STARTTLS (Port 587) - Recommended for most providers. Connection starts unencrypted and upgrades to TLS.
    • TLS/SSL (Port 465) - For servers requiring immediate encryption from connection start.
    • None (Port 25) - No encryption. Only use for internal/legacy servers on trusted networks.

​
Username

Your SMTP authentication username.
  • Required: Yes
  • Usually: Your full email address
  • Note: Some providers use a separate SMTP username. Check your provider’s documentation.

​
Password

Your SMTP authentication password.
  • Required: Yes
  • Important security notes:

​
Validate SSL Certificate

Controls whether the server’s SSL certificate is verified.
  • Required: No (defaults to disabled)
  • Enable when: Using production email servers with valid SSL certificates
  • Disable when: Using self-signed certificates (common with private hosting mail servers)
  • Security note: Disabling certificate validation makes the connection vulnerable to man-in-the-middle attacks. Only disable for trusted internal servers.

​
Common Provider Configurations

​
Gmail / Google Workspace

Host: smtp.gmail.com
Port: 587
Encryption: STARTTLS
Username: [email protected] (or [email protected] for Workspace)
Password: App Password (required if 2FA enabled)
Important:
  • Enable “Less secure app access” or use App Passwords
  • Google may block connections from new locations initially

​
Microsoft 365 / Outlook

Host: smtp.office365.com
Port: 587
Encryption: STARTTLS
Username: [email protected]
Password: Account password or App Password
Note: Microsoft requires SMTP AUTH to be enabled for the mailbox.

​
Zoho Mail

Host: smtp.zoho.com (or smtp.zoho.eu, smtp.zoho.in based on region)
Port: 587
Encryption: STARTTLS
Username: [email protected]
Password: App-specific password

​
Amazon SES

Host: email-smtp.{region}.amazonaws.com
Port: 587
Encryption: STARTTLS
Username: SMTP username (from SES console, not IAM)
Password: SMTP password (from SES console)
Note: Sender email must be verified in SES.

​
cPanel / Hosting Providers

Host: mail.yourdomain.com (or server hostname)
Port: 465
Encryption: TLS/SSL
Username: [email protected]
Password: Email account password
Validate SSL: Disabled (if using self-signed certificate)

​
Troubleshooting

​
Connection Timeout

Symptoms: Integration test fails with “Connection timed out” Possible causes:
  1. Wrong host or port - Double-check your provider’s SMTP settings
  2. Firewall blocking - Your network may block outgoing SMTP ports
  3. Wrong encryption setting - Try switching between STARTTLS and TLS/SSL
  4. Server is slow - Some hosting providers have slower mail servers
Solutions:
  • Verify host and port are correct
  • Try port 587 with STARTTLS first, then 465 with TLS/SSL
  • Contact your network administrator about firewall rules

​
Authentication Failed

Symptoms: Error “Authentication failed” or “535” error code Possible causes:
  1. Wrong username/password - Re-check credentials
  2. 2FA enabled without app password - Generate an app-specific password
  3. SMTP access disabled - Enable SMTP in your email provider settings
  4. Account security block - Provider blocked the connection as suspicious
Solutions:
  • For Gmail: Enable 2FA and create an App Password
  • For Microsoft 365: Ensure SMTP AUTH is enabled for the account
  • Check your email for security alerts from your provider
  • Try logging into webmail to unlock the account

​
Certificate Error

Symptoms: Error mentioning “certificate”, “SSL”, or “TLS” Possible causes:
  1. Self-signed certificate - Server uses a certificate not trusted by default
  2. Expired certificate - Server’s SSL certificate has expired
  3. Wrong encryption setting - Mismatch between port and encryption type
Solutions:
  • Disable “Validate SSL Certificate” for self-signed certs
  • Contact your hosting provider about certificate issues
  • Ensure encryption setting matches the port (587=STARTTLS, 465=TLS/SSL)

​
Emails Going to Spam

Symptoms: Emails delivered but land in recipients’ spam folders This is NOT a code issue - it’s related to email authentication and reputation. Solutions:
  1. Configure SPF record - Add your sending server to your domain’s SPF record
  2. Set up DKIM - Enable DKIM signing in your email provider
  3. Configure DMARC - Add a DMARC policy to your DNS
  4. Use a consistent sender - Don’t change your “From” address frequently
  5. Warm up your domain - Start with low volumes and gradually increase
  6. Check blacklists - Verify your sending IP isn’t blacklisted

​
Connection Refused

Symptoms: Error “ECONNREFUSED” Possible causes:
  1. Wrong port - Server doesn’t accept connections on that port
  2. Server down - SMTP server is temporarily unavailable
  3. IP blocked - Your IP may be blocked by the server
Solutions:
  • Try different ports (587, 465, 25)
  • Contact your email provider to verify server status
  • Check if your IP needs to be whitelisted

​
Best Practices

​
Security

  1. Use encryption - Always use STARTTLS or TLS/SSL. Avoid unencrypted connections.
  2. Use app passwords - Don’t use your main account password when app passwords are available.
  3. Enable certificate validation - Only disable for known self-signed certificates.
  4. Rotate credentials - Periodically update your SMTP password.

​
Deliverability

  1. Set up email authentication - Configure SPF, DKIM, and DMARC for your domain.
  2. Use a consistent sender address - Stick to one or few sender addresses.
  3. Monitor bounce rates - High bounce rates hurt your reputation.
  4. Don’t send spam - Only send to recipients who’ve opted in.

​
Performance

  1. Use a reliable provider - Enterprise email providers offer better uptime.
  2. Monitor sending limits - Don’t exceed your provider’s rate limits.
  3. Handle failures gracefully - Implement retry logic for temporary failures.

​
Email Authentication (DNS Records)

For optimal deliverability, configure these DNS records:

​
SPF (Sender Policy Framework)

Tells receiving servers which servers can send email for your domain. 
Type: TXT
Host: @
Value: v=spf1 include:_spf.google.com include:your-other-providers.com ~all

​
DKIM (DomainKeys Identified Mail)

Adds a digital signature to verify emails weren’t tampered with.
  • Usually configured in your email provider’s admin panel
  • Provider generates a DNS record to add to your domain

​
DMARC (Domain-based Message Authentication)

Tells receiving servers what to do with emails that fail SPF/DKIM checks. 
Type: TXT
Host: _dmarc
Value: v=DMARC1; p=quarantine; rua=mailto:[email protected]

​
Testing Your Configuration

After setting up SMTP integration:
  1. Connection test - Heffl tests the connection when you save the integration
  2. Send a test email - Send an email to yourself to verify delivery
  3. Check spam folder - Ensure emails don’t land in spam
  4. Test from different clients - Verify emails look correct in various email clients
  5. Check email headers - Verify SPF/DKIM/DMARC pass in email headers

​
Frequently Asked Questions

​
Can I use Gmail’s SMTP for free?

Yes, but with limitations:
  • Free Gmail: ~500 emails/day
  • Google Workspace: ~2,000 emails/day
  • Requires App Password if 2FA is enabled

​
Why do I need an App Password?

If you have 2-Factor Authentication enabled (which you should), your regular password won’t work for SMTP. App Passwords are special passwords generated for specific applications that bypass 2FA.

​
Can I send from any email address?

No. You can only send from:
  • The email address associated with your SMTP account
  • Aliases configured in your email provider
  • Verified sender addresses (for services like Amazon SES)

​
What happens if SMTP connection fails?

Heffl queues emails and retries failed sends. If the SMTP server is temporarily unavailable, emails will be sent once the connection is restored.

​
How many emails can I send?

This depends on your email provider’s limits:
  • Gmail: 500/day (free) or 2,000/day (Workspace)
  • Microsoft 365: 10,000/day
  • Amazon SES: Based on your account tier
  • Custom hosting: Check with your provider

​
Is my password stored securely?

Yes. SMTP passwords are encrypted using AES-256-GCM before storage and decrypted only when needed to send emails.