SMTP Relay Guide

When to use SMTP relay

SMTP relay is useful for:

1. Legacy applications.
2. CMS and commerce platforms.
3. Framework mailers.
4. Monitoring tools.
5. Any system that supports SMTP but not custom HTTP APIs.

For new application code, prefer the transactional email guide.

Configure the client

Use the SMTP settings from your dashboard:

Use port 465 only when the client requires implicit TLS.

Verify From domains

SMTP does not bypass domain checks. The visible From domain still needs to be verified and authenticated.

If a client sends from many addresses under one domain, verify the domain rather than each individual mailbox.

Preserve headers you need

Many SMTP clients let you add custom headers. Use them for correlation:

X-Postscale-Metadata-order-id: ord_456
X-Postscale-Metadata-template: receipt

Do not put secrets or personal data into custom headers unless you are comfortable with every receiving system seeing them.

Handle SMTP errors correctly

SMTP responses can fail before Postscale accepts the message. Treat 4xx responses as temporary and 5xx responses as permanent unless the client documentation says otherwise.

Common causes:

1. Invalid credentials.
2. Unverified From domain.
3. Recipient suppressed.
4. Message too large.
5. TLS or port mismatch.

After Postscale accepts the message, use webhooks for final delivery state.