Skip to main content

​
Setup

Courier’s SMTP integration uses NodeMailer under the hood. In Courier, navigate to the SMTP Integration page and enter your SMTP host, username, password, and From Address, then click “Save.” You can override these settings on a per-message basis using provider overrides.
Courier connects to your SMTP server from Courier’s own IP addresses. If your server uses IP allowlisting, contact Courier Support for the current list of egress IPs.

​
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": "recipient@example.com"
    }
    // ... rest of message definition
  }
}

​
Overrides

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": "NOTIFICATION_TEMPLATE_ID",
    "to": {
      "email": "alice@acme.com"
    },
    "providers": {
      "smtp": {
        "override": {
          "body": {
            "attachments": [
              {
                "filename": "document.pdf",
                "content": "aGVsbG8gd29ybGQh",
                "encoding": "base64",
                "contentType": "application/pdf"
              }
            ]
          }
        }
      }
    }
  }
}
Everything inside of 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": "NOTIFICATION_TEMPLATE_ID",
    "to": {
      "email": "alice@acme.com"
    },
    "providers": {
      "smtp": {
        "override": {
          "config": {
            "auth": {
              "user": "username",
              "pass": "hunter2"
            },
            "host": "smtp.example.com",
            "secure": true,
            "port": 465
          }
        }
      }
    }
  }
}
STARTTLS (port 587, recommended): 
{
  "message": {
    "template": "NOTIFICATION_TEMPLATE_ID",
    "to": {
      "email": "alice@acme.com"
    },
    "providers": {
      "smtp": {
        "override": {
          "config": {
            "host": "smtp.yourdomain.com",
            "port": 587,
            "secure": false,
            "requireTLS": true,
            "auth": {
              "user": "user@yourdomain.com",
              "pass": "your-password"
            }
          }
        }
      }
    }
  }
}
Implicit TLS (port 465): 
{
  "message": {
    "template": "NOTIFICATION_TEMPLATE_ID",
    "to": {
      "email": "alice@acme.com"
    },
    "providers": {
      "smtp": {
        "override": {
          "config": {
            "host": "smtp.yourdomain.com",
            "port": 465,
            "secure": true,
            "auth": {
              "user": "user@yourdomain.com",
              "pass": "your-password"
            }
          }
        }
      }
    }
  }
}
Common provider settings:
ProviderHostPortsecurerequireTLS
Office 365smtp.office365.com587falsetrue
Gmail (app password)smtp.gmail.com587falsetrue
On-prem Exchangemail.yourdomain.com587falsetrue
Custom (implicit TLS)varies465true-
Transport options reference:
OptionTypeDescription
hoststringSMTP server hostname
portnumberSMTP port (commonly 25, 465, 587)
securebooleanUse SSL (true for port 465)
requireTLSbooleanRequire STARTTLS (true for port 587)
authobjectAuthentication credentials { user, pass }
tlsobjectTLS options (see NodeMailer TLS docs)
connectionTimeoutnumberConnection timeout in milliseconds
socketTimeoutnumberSocket timeout in milliseconds
Available Options: See the NodeMailer SMTP transport documentation for all available config override options.

​
Security Best Practices

  • Use app-specific passwords for Office 365 and Gmail instead of regular account passwords.
  • Create dedicated service accounts for sending rather than using personal accounts.
  • Store credentials in Courier Studio rather than passing them in every API request.
  • Always use TLS: set requireTLS: true for port 587, secure: true for port 465.
  • For HIPAA or data residency requirements, use a direct connection to your on-premises SMTP server.

​
Troubleshooting

Courier verifies your SMTP connection before each send. If verification fails, the message is not sent and an error is returned. Connection timeouts (ETIMEDOUT) and temporary server unavailability are retried automatically.
  • Check that 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
  • 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
  • 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