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 | Default address replies should go to when an endpoint output does not set its own Reply-To |
Endpoint-level email Reply-To settings are more specific than the target default. If an endpoint output sets a manual or dynamic Reply-To value, that value is used; otherwise PayloadRelay falls back to the SMTP target's Reply-To field.
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.
SMTP relay targets cannot be attached to endpoint outputs, used for alerts/failover, or tested until verification succeeds. A failed verification clears the target's ready status; fix the SMTP configuration and verify again.
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
Each accepted source event counts once against the monthly accepted-event quota. BYO-SMTP and platform-email fan-out or retries do not add quota charges.
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 |