Skip to main content

​
Enable SMTP

First, enable SMTP for the project you want to use. You can find this setting under your Projects.
Project settings with Enable SMTP option.

​
SMTP Configuration

Use these settings to configure your application or email client:
SettingValue
Hostsmtp.lettermint.co
Port587 (see available ports )
AuthenticationPLAIN, LOGIN and CRAM-MD5 are supported
Usernamelettermint
PasswordYour Lettermint API token

​
Available ports

Lettermint supports multiple SMTP ports to accommodate different network environments and security requirements:
PortSecurityNotes
25STARTTLS (optional encryption upgrade)Not recommended, blocked by many ISPs and cloud providers
587STARTTLS (encryption upgrade)Recommended as alternative if Implicit TLS is not supported
465Implicit TLS (SMTPS, encrypted from connection)Recommended for best security
2525STARTTLS (encryption upgrade)Alternative to port 25
2465STARTTLS (encryption upgrade)Alternative to port 465
2587STARTTLS (encryption upgrade)Alternative to port 587

​
Understanding TLS Options

  • STARTTLS: Connection starts unencrypted and upgrades to TLS encryption. Used on ports 25, 587, 2525, 2465 and 2587.
  • SMTPS: Connection is encrypted from the start. Used on port 465.
If you’re not sure which port to use, start with port 587. It’s widely accepted and provides good security through STARTTLS.
Port 25 is often blocked by ISPs and cloud providers to prevent spam. We recommend using alternative ports whenever possible.

​
Authentication

Authentication is always required when using Lettermint’s SMTP service:
  1. Use lettermint as username and your API token as password
  2. Always use TLS encryption (either STARTTLS or Implicit TLS) to protect your credentials
  3. Your API token can be found in your dashboard under API settings

​
Custom Headers

​
X-Lettermint-Route

You can control email routing by including the X-Lettermint-Route header in your SMTP messages. This header accepts a route’s slug to specify which route should handle the email. 
X-Lettermint-Route: your-route-slug
This is useful when you have multiple routes configured in your project and want to explicitly specify which route should process a particular email. If this header is not provided, the email will be routed according to your project’s default route, which is always the original outgoing transactional route.

​
X-LM-Tag (or X-Tag)

Tag your emails for organization, filtering, and analytics by including the X-LM-Tag header. Tags help you categorize emails by campaign, department, or any custom classification. 
X-LM-Tag: order-confirmation
Tag requirements:
  • Maximum length: 255 characters
  • Allowed characters: Letters, numbers, underscores, hyphens, and spaces
  • Pattern: ^[a-zA-Z0-9_-]+(?:\s[a-zA-Z0-9_-]+)*$
  • One tag per message
Valid examples:
  • newsletter
  • order-confirmation
  • Password Reset
  • Invoice_2024
Alternative header: You can also use X-Tag for compatibility with Symfony Mailer, but X-LM-Tag takes precedence if both are present.
Learn more about organizing emails with tags in the Tags documentation.

​
X-LM-Metadata-* (or X-Metadata-*)

Attach custom metadata to your emails for tracking and webhook payloads. Metadata headers use a prefix pattern where anything after X-LM-Metadata- becomes the metadata key. 
X-LM-Metadata-order_id: 12345
X-LM-Metadata-customer_id: cust_789
X-LM-Metadata-campaign: summer-sale
Key features:
  • Keys preserve their casing (e.g., X-LM-Metadata-UserID → {"UserID": "value"})
  • Values are stored as strings
  • Metadata is included in webhook payloads but not sent to recipients
  • Useful for correlating emails with your application data
Alternative prefix: You can also use X-Metadata- for compatibility with Symfony Mailer, but X-LM-Metadata- takes precedence if both are present for the same key.

​
Rate limits

SMTP relay follows the same rate limits as our API: no rate limit at all!

​
Testing Your Configuration

Test your SMTP setup with a simple command-line tool: 
# Install swaks (SMTP testing tool)
# On macOS: brew install swaks
# On Ubuntu: apt-get install swaks

swaks --to recipient@example.com \
      --from sender@yourdomain.com \
      --server smtp.lettermint.co:587 \
      --auth LOGIN \
      --auth-user lettermint \
      --auth-password your-api-key \
      --tls \
      --header "Subject: SMTP Test" \
      --header "X-Lettermint-Route: your-route-slug" \
      --header "X-LM-Tag: test-email" \
      --header "X-LM-Metadata-source: swaks-test" \
      --body "This is a test email via SMTP."
For language-specific examples and application configurations, please refer to our dedicated guides in the documentation.
⌘I