How to Set Up Bird as Your SMTP Relay

Key Takeaways

• Purpose: configure Bird as the outgoing mail server for an email client, so you can send from your own domain without writing any code.

• Core setup:

  1. Verify your sending domain in Bird.
  2. Create an API key that is allowed to send.
  3. In your email client, fill in the host, port, username and password from Connection settings in our SMTP guide.
  4. Send a test message and confirm it arrives.

• Worth knowing before you start:

  • Your API key's region decides which host you connect to, so take the host from the guide rather than from another tutorial.
  • The username is a fixed value rather than your email address, and the password is the API key rather than your account password. Both catch people out.
  • Use a login address on a different domain from your sending domain, so a sending problem cannot lock you out of support.

• Alternative: the email API gives you more control and is the better fit for an application. SMTP is the simpler path for a mail client, a legacy system, or anything that already speaks it.

Many frameworks, languages and tools come with SMTP support built in, and the piece they leave to you is the server at the other end. That is what a relay provides.

This post walks through the setup end to end with a mail client, using Gmail as the client and a domain you own as the sending domain. It deliberately does not restate the connection values: those live in the SMTP guide, which is kept current, and copying them into a blog post is how tutorials drift out of date.

What is an SMTP relay?

A service that provides a dedicated outgoing mail server, so your messages leave through infrastructure built for sending rather than through a mailbox host.

Businesses use one to keep bulk and transactional mail off the domain that carries internal email. If a send goes wrong, the reputation damage lands on the sending domain rather than on the address your colleagues use every day.

Does Bird support SMTP?

Yes, and it is one of two ways to send. The email API is the better choice when an application generates the mail and you want per-message control. SMTP is the better choice when something already speaks SMTP and you would rather not write an integration for it.

Mail submitted over SMTP is treated exactly like mail sent through the API: the same domain verification, DKIM signing, suppression handling, tracking and events apply to both. Choosing SMTP does not put you on a lesser path.

Before you start

Two things have to exist before a client can connect.

A verified sending domain. Bird will not send from a domain you have not proven you control, which is what stops anyone else sending as you. Verification is a DNS change.

An API key that may send. The key doubles as your SMTP password, so treat it as a credential: keep it out of shared documents, and rotate it if it leaks.

One piece of advice that costs nothing and saves an afternoon: sign in to Bird with an address on a different domain from the one you are configuring. If sending from that domain breaks, you can still reach support from an inbox that works.

Fill in the client

Every mail client asks for the same four things: a host, a port, a username and a password. Take all four from Connection settings.

Two of them are not what a first guess would suggest. The username is a fixed value rather than your email address. The password is the API key rather than your account password. If a client rejects your credentials, check those two before anything else.

The port question has its own answer: see what SMTP port should I use? for what each option does and which to prefer. The short version is that your connection is encrypted before your credentials are sent, on every port we offer for submission.

One default is worth changing before you send anything real. Options with no place in a MIME message come from the key's SMTP configuration rather than from the message, and an unconfigured key has open and click tracking enabled. That rewrites the links in your outgoing mail, which is rarely what you want from a mail client. What comes from the message, and what comes from the key's configuration covers it and the rest of the per-key defaults.

In Gmail this is the "Send mail as" flow in settings, which asks for a server, a port, a username and a password, then verifies the address by emailing it a confirmation link. Google documents the fields for work and school accounts; a personal account presents the flow differently, so check what yours asks for rather than assuming the four map one to one. Other clients word it differently and want the same things.

Confirm it works

Send one message to an address you can read, and confirm it arrives.

If it does not, the fastest way to tell a credential problem from a network problem is to open the connection by hand: test your SMTP connection manually using telnet walks through a session and shows what each response means. A connection that never opens is a blocked port or a firewall. A connection that opens and then refuses your login is a credential or a permission problem.

Q&A

What is an SMTP relay?

A mail-sending service that routes your outgoing messages through a server built for delivery, rather than through the mail host that runs your mailboxes.

Why use a relay instead of my regular mail host?

A mailbox host is built to store and retrieve mail for people. A relay is built to send mail on behalf of systems, and it gives you the delivery events and per-message visibility a mailbox host generally does not.

Can I use this with Gmail or Outlook?

Yes. Any client that can authenticate with a username and password over TLS can connect, given the connection settings and a verified sending domain. We accept AUTH PLAIN and AUTH LOGIN, so a client that offers only OAuth or CRAM-MD5 cannot connect however well it speaks SMTP.

What is the difference between the API and SMTP?

The API suits an application sending programmatically and wanting control over each message. SMTP suits a mail client, a legacy system, or any tool that already supports it. Both go through the same sending pipeline.

How do I test connectivity?

Send a test message from the configured client and see whether it arrives. To go lower, telnet to port 587 will show you the banner and the EHLO response, which is enough to prove the port is open and reachable, but it cannot finish the login: authentication happens after STARTTLS, and telnet cannot speak TLS. Port 465 is encrypted from the first byte, so telnet shows nothing readable there at all and openssl s_client is the tool for it.