Custom SMTP Server (BYO-SMTP)
Configure a relay target to deliver emails via your own SMTP provider.
Custom SMTP Server (BYO-SMTP)
By default, PayloadRelay sends email relay deliveries through its own email infrastructure. With BYO-SMTP, you can configure a relay target to send emails through your own SMTP server (AWS SES, SendGrid, Postmark, Mailgun, Office 365, Gmail, or any SMTP-compatible service).
Why use BYO-SMTP?
- Sender domain control — emails arrive from your own domain, improving deliverability
- Compliance — keep email traffic within your own infrastructure for compliance requirements
- Cost transparency — pay your email provider directly for each delivery
Configuration
In the relay target editor, select Custom SMTP server as the delivery mode for an EMAIL target, then configure:
| Field | Required | Description |
|---|---|---|
| Host | Yes | SMTP server hostname (e.g. smtp.sendgrid.net) |
| Port | Yes | SMTP port (typically 587 for STARTTLS, 465 for SSL/TLS) |
| Security | Yes | STARTTLS (recommended), SSL/TLS, or None |
| Username | Yes | SMTP authentication username |
| Password | Yes | SMTP authentication password |
| From address | Yes | Sender email address (must be authorized on your SMTP provider) |
| From name | No | Display name shown in the sender field |
| Reply-To | No | Address replies should go to |
Common provider settings
| Provider | Host | Port | Security | Notes |
|---|---|---|---|---|
| AWS SES (SMTP) | email-smtp.us-east-1.amazonaws.com | 587 | STARTTLS | Use SMTP credentials from SES console |
| SendGrid | smtp.sendgrid.net | 587 | STARTTLS | Username is always apikey, password is API key |
| Postmark | smtp.postmarkapp.com | 587 | STARTTLS | Username & password are the Server API Token |
| Mailgun | smtp.mailgun.org | 587 | STARTTLS | Use SMTP credentials from Mailgun domain settings |
| Office 365 | smtp.office365.com | 587 | STARTTLS | Use your M365 account credentials or app password |
| Gmail | smtp.gmail.com | 587 | STARTTLS | Requires an App Password |
Verification
Use the Verify connection button in the relay target editor to test your SMTP configuration. PayloadRelay will open a connection to your SMTP server and send a test message to the target email address. The result (success or error) is stored on the target and shown in the UI.
Verification may be temporarily rate-limited after repeated attempts.
Security
- SMTP passwords are stored securely and are not shown again after saving.
- Connections to your SMTP server use TLS (STARTTLS or SSL/TLS) by default.
- Rotate the SMTP password in your provider and update the target if you suspect exposure.
Quota interaction
All relay deliveries — both BYO-SMTP and platform email — count against your monthly request quota.
Troubleshooting
| Error | Likely cause |
|---|---|
Connection refused | Wrong host or port; firewall blocking outbound SMTP |
Authentication failed | Wrong username or password |
STARTTLS is required | Use STARTTLS security, not None |
SSL handshake failed | Try STARTTLS instead of SSL/TLS, or check the port |
Sender address rejected | Your From address is not authorized on the SMTP server |
Recipient address rejected | SMTP server requires authenticated senders or domain verification |