Custom SMTP Server (BYO-SMTP)
Add a custom SMTP target and do a connection test before use.
By default, PayloadRelay does the email delivery. With BYO-SMTP, you can configure a relay target to send the email through your SMTP server. Examples are AWS SES, SendGrid, Postmark, Mailgun, Office 365, and Gmail.
Why use BYO-SMTP#
- Sender domain control: the email comes from your domain.
- Compliance: the email traffic stays in your infrastructure.
- Cost transparency: you pay your email provider for each delivery.
Configuration#
In the relay target editor, select Custom SMTP server as the delivery mode for an EMAIL target. Enter these values:
| Field | Necessary | Description |
|---|---|---|
| Host | Yes | The SMTP server hostname, for example, smtp.sendgrid.net |
| Port | Yes | The SMTP port. 587 is usual for STARTTLS, and 465 for SSL/TLS. |
| Security | Yes | STARTTLS (recommended), SSL/TLS, or None |
| Username | Yes | The SMTP authentication username |
| Password | Yes | The SMTP authentication password |
| From address | Yes | The sender email address. Your SMTP provider must permit it. |
| From name | No | The display name in the sender field |
| Reply-To | No | The default destination for a reply, if an endpoint destination does not set its own Reply-To |
The Reply-To value on the endpoint has precedence over the default of the target. If an endpoint destination sets a manual or dynamic Reply-To value, PayloadRelay uses that value. If it does not, PayloadRelay uses the Reply-To field of the SMTP target.
Common provider configurations#
| Provider | Host | Port | Security | Notes |
|---|---|---|---|---|
| AWS SES (SMTP) | email-smtp.us-east-1.amazonaws.com | 587 | STARTTLS | Use the SMTP credentials from the SES console |
| SendGrid | smtp.sendgrid.net | 587 | STARTTLS | The username is always apikey. The password is the API key. |
| Postmark | smtp.postmarkapp.com | 587 | STARTTLS | The username and the password are the Server API Token |
| Mailgun | smtp.mailgun.org | 587 | STARTTLS | Use the SMTP credentials from the Mailgun domain configuration |
| Office 365 | smtp.office365.com | 587 | STARTTLS | Use your M365 account credentials or an app password |
| Gmail | smtp.gmail.com | 587 | STARTTLS | Needs an App Password |
Do a connection test#
To do a test of the SMTP configuration, use the Verify connection button in the relay target editor. PayloadRelay connects to the SMTP server and sends a test message to the target email address. The result appears in the target editor.
Before the connection test succeeds, do not attach an SMTP relay target to an endpoint destination. Do not use it for an alert, a failover, or a test. A failed test clears the Available status of the target. Correct the SMTP configuration, then do the test again.
Repeated attempts can cause a temporary rate limit.
Security#
- PayloadRelay stores an SMTP password securely. PayloadRelay does not show the password after you save it.
- By default, a connection to the SMTP server uses TLS through STARTTLS or SSL/TLS.
- If you think that the password became known, change the SMTP password in the provider. Then update the target.
Quota interaction#
Each accepted source event counts one time against the monthly accepted-event quota. The fan-out and the retries of BYO-SMTP and of the platform email add no quota charge.
Troubleshooting#
| Error | Probable cause |
|---|---|
Connection refused | The host or the port is wrong. A firewall can block the outbound SMTP. |
Authentication failed | The username or the password is wrong |
STARTTLS is required | Use the STARTTLS security, not None |
SSL handshake failed | Use STARTTLS in place of SSL/TLS, or examine the port |
Sender address rejected | Your SMTP server does not permit your From address |
Recipient address rejected | The SMTP server needs an authenticated sender or a domain verification |