Getting started / SMTP relay

SMTP relay

If your application already sends mail over SMTP, you do not need the API. Change five settings and everything else stays as it is — the same pipeline, the same authentication, the same events.

New to relays? The SMTP relay glossary entry explains what one replaces and how it compares with an API. Setting up a self-hosted app? The integration pages give tested settings for each one.

Create a credential

In the dashboard, open Transactional, choose your sending domain, and find the SMTP section. Create Credential generates a username and password for that domain.

Copy the password when it appears. Create as many credentials as you have places that send — one per application or environment means you can revoke one without re-deploying the others.

Settings

Host smtp.pharosinfra.net Same host for every account.

Port 587 or 2525 Same service on both. Use 2525 where the host blocks 587.

Encryption STARTTLS Some mailers call this "TLS". Not SSL, and not port 465.

Authentication LOGIN or PLAIN Either works. Most mailers choose for you.

Username from the dashboard Generated with the credential. Not your account email.

Password from the dashboard Shown when the credential is created.

The credential is bound to its sending domain, and mail leaves from that domain — the same rule the API follows, described under authentication.

Check it before you wire it in

Send one message by hand first. If this works, the credentials and the connection are right, and anything that fails afterwards is your mailer's configuration rather than ours.

When it does not connect

Authentication failed. The username is the generated one, not your account email address. Check the credential has not been deleted in the dashboard. New accounts are reviewed before the first send, and until then the relay answers 535 Authentication credentials invalid even with the right password.
Connection times out. Some hosting providers block outbound port 587. DigitalOcean blocks it on every droplet, and Linode blocks it on some new accounts. Switch to port 2525, which is the same service. Test from the machine that will actually send, not from your laptop.
TLS errors. Use STARTTLS on 587, not implicit SSL on 465. A mailer offering "SSL/TLS" and "STARTTLS" as separate options wants the second.
Mail sends but arrives from a different address. That is the sending domain being enforced, not a bug — see authentication.

API or SMTP?

Both reach the same pipeline, so the choice is about your code rather than about delivery. SMTP suits an application that already sends mail and a framework mailer you would rather not replace. The API gives you a message id in the response, idempotency, and errors you can branch on, which SMTP cannot express beyond a status code at connection time.

If those five settings currently point at another provider, the relay is the whole migration on the application side — but it is not the whole migration. The suppression list and the event webhook do not move with the credentials. There are step-by-step pages for SendGrid, Postmark and Mailgun, each covering what to export before the first send.

One-off testswaks

swaks --to recipient@example.com \
      --from noreply@yourapp.com \
      --server smtp.pharosinfra.net --port 587 --tls \
      --auth LOGIN \
      --auth-user '<USER>' --auth-password '<PASS>' \
      --header 'Subject: Test via swaks' \
      --body 'Hello from Pharos.'

Framework config.env

MAIL_MAILER=smtp
MAIL_HOST=smtp.pharosinfra.net
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=$PHAROS_SMTP_USER
MAIL_PASSWORD=$PHAROS_SMTP_PASS
MAIL_FROM_ADDRESS=noreply@yourapp.com