Overview
Courier’s SMTP integration uses NodeMailer under the hood, giving you full control over both message content and transport configuration. The integration automatically verifies your SMTP connection before sending messages.
SMTP provider configuration is managed in the Courier Studio. You can override these settings on a per-message basis using provider overrides in the Send API.
Profile Requirements
To deliver a message to a recipient over SMTP, Courier must be provided the recipient’s email address. This value should be included in the recipient profile as email:
{
"message": {
"to": {
"email": "[email protected]"
}
// ... rest of message definition
}
}
Override
You can override both the message content and SMTP transport configuration on a per-message basis using provider overrides in the Send API.
Message Override
You can use a provider override to replace what we send to SMTP using NodeMailer. For example, you can add an attachment to your request:
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"body": {
"attachments": [
{
"filename": "document.pdf",
"content": "aGVsbG8gd29ybGQh",
"encoding": "base64",
"contentType": "application/pdf"
}
]
}
}
}
}
}
}
message.providers.smtp.override.body will be merged with Courier’s generated message and passed directly to NodeMailer. You can see all the available options by visiting the NodeMailer message options documentation.
Transport Override
You may also override the SMTP transport configuration using values passed to message.providers.smtp.override.config. These settings will override your stored provider configuration for this specific message.
Basic Example:
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"config": {
"auth": {
"user": "username",
"pass": "hunter2"
},
"host": "smtp.example.com",
"secure": true,
"port": 465
}
}
}
}
}
}
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"config": {
"host": "smtp.office365.com",
"port": 587,
"secure": false,
"requireTLS": true,
"auth": {
"user": "[email protected]",
"pass": "your-app-specific-password"
}
}
}
}
}
}
}
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"config": {
"host": "mail.yourdomain.com",
"port": 587,
"secure": false,
"requireTLS": true,
"auth": {
"user": "domain\\username",
"pass": "your-password"
}
}
}
}
}
}
}
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"config": {
"host": "smtp.gmail.com",
"port": 587,
"secure": false,
"requireTLS": true,
"auth": {
"user": "[email protected]",
"pass": "your-app-specific-password"
}
}
}
}
}
}
}
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"config": {
"host": "smtp.yourdomain.com",
"port": 587,
"secure": false,
"requireTLS": true,
"auth": {
"user": "[email protected]",
"pass": "your-password"
}
}
}
}
}
}
}
{
"message": {
"template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
"to": {
"email": "[email protected]"
},
"providers": {
"smtp": {
"override": {
"config": {
"host": "smtp.yourdomain.com",
"port": 465,
"secure": true,
"auth": {
"user": "[email protected]",
"pass": "your-password"
}
}
}
}
}
}
}
| Option | Type | Description |
|---|
host | string | SMTP server hostname |
port | number | SMTP port (commonly 25, 465, 587) |
secure | boolean | Use SSL (true for port 465) |
requireTLS | boolean | Require STARTTLS (true for port 587) |
auth | object | Authentication credentials { user, pass } |
tls | object | TLS options (see NodeMailer TLS docs) |
connectionTimeout | number | Connection timeout in milliseconds |
socketTimeout | number | Socket timeout in milliseconds |
config override options.
Security Best Practices
Authentication
- Use App-Specific Passwords: For Office 365 and Gmail, use app-specific passwords instead of your regular account password
- Service Accounts: Create dedicated service accounts for sending emails rather than using personal accounts
- Credential Storage: Store SMTP credentials securely in Courier Studio rather than passing them in every API request
Encryption
- Always Use TLS: Set
requireTLS: true for port 587 connections
- Use SSL for Port 465: Set
secure: true when using port 465
- Verify Certificates: Don’t disable certificate validation unless absolutely necessary
Healthcare & Compliance
- On-Premises Exchange: For HIPAA compliance, use direct SMTP connection to your on-premises Exchange server
- Data Residency: Ensure your SMTP server meets your data residency requirements
- Audit Logging: Monitor SMTP connection logs in Courier for compliance auditing
Connection Verification
Courier automatically verifies your SMTP connection configuration before sending messages. If the connection fails during verification, the message will not be sent and you’ll receive an error.
Error Handling
Retryable Errors:
- Connection timeouts (
ETIMEDOUT)
- Temporary server unavailability
Permanent Errors:
- Invalid credentials
- Invalid host/port configuration
- SMTP server rejection
Troubleshooting
Connection Timeouts:
- Check firewall rules allow outbound connections to your SMTP server
- Verify the SMTP host and port are correct
- Ensure your SMTP server is accessible from Courier’s infrastructure
Authentication Failures:
- Verify username and password are correct
- For Office 365, ensure you’re using an app-specific password if MFA is enabled
- Check if your account has permission to send emails via SMTP
TLS/SSL Errors:
- Verify your SMTP server supports the requested encryption method
- Check certificate validity if using custom certificates
- Ensure
secure and requireTLS settings match your server configuration
