Send email over SMTP

If your application, framework, or off-the-shelf software already speaks SMTP, you can send through Bird by changing three connection settings and nothing else. Rails ActionMailer, Laravel, Django, WordPress, a scan-to-email printer, an ERP: anything that can submit mail to a relay works. For teams migrating from another provider it is a credentials swap, not an integration.

Mail submitted over SMTP goes through the same pipeline as the email API: the same domain verification, IP pools, DKIM signing, suppression handling, tracking, events, and analytics. SMTP is a second door into one system, not a parallel one.

What you need first

A verified sending domain. The address you put in MAIL FROM (and the message From header) must belong to a domain you have verified in this workspace. See Sending domains.
An API key with the emails scope. SMTP uses your normal Bird API keys. There is no separate SMTP username or password to manage. Create a key with email sending enabled from the API keys page. A key without the emails scope cannot send, and neither can a verify-only key.

Connection settings

Point your client at the SMTP host for your key's region. The region is the prefix in the key itself: a bk_eu1_… key sends through the eu1 host, a bk_us1_… key through us1.

Region	Host
EU	eu1.smtp.bird.com
US	us1.smtp.bird.com

Port	Encryption
465	Implicit TLS (SMTPS)
587	STARTTLS
2525	STARTTLS

Use whichever your client supports:

Port 465, implicit TLS (SMTPS). The connection is encrypted from the first byte, before any command is sent. In most libraries this is the "SSL/TLS" or "SMTPS" option.
Ports 587 and 2525, STARTTLS. The connection opens in plaintext and upgrades to TLS with the STARTTLS command before authentication. This is the "STARTTLS" (sometimes just "TLS") option. Pick 2525 if your network blocks 587.

Either way the session is encrypted before your credentials are sent, so they never travel in the clear: on 587 and 2525 Bird refuses AUTH until STARTTLS has run. Port 25 is not offered for submission.

Authenticating

Authenticate with AUTH PLAIN or AUTH LOGIN. The username is the literal string bird, and the password is your API key:

Przykład kodu

Username: bird
Password: bk_eu1_your_api_key

The username is a fixed literal — it carries no identity, the API key in the password field is what authenticates. In most SMTP tools you paste your API key into the password field and set the username to bird.

What the message carries, and what the key's config carries

Everything with a natural place in a MIME message comes from the message itself: the From, To, Cc, and Reply-To headers, the subject, the HTML and text bodies, and attachments and inline images. Recipients are taken from the SMTP envelope (RCPT TO). An address in RCPT TO that isn't in a visible To or Cc header is treated as a Bcc. A message can have at most 50 recipients across to, cc, and bcc, and the total message size is capped at 20 MB.

The send options that have no place in a MIME message (which IP pool to send from, the content category, tags, and open/click tracking) come from a per-key SMTP configuration. A key with no configuration sends with sensible defaults: your organization's default pool, the transactional category, and tracking on. To customize them, open the SMTP page and configure the key. Because the defaults live on the key, you can give each application its own key: a wordpress-prod key on the marketing pool with a source=wordpress tag, an erp key on a dedicated pool, each with no per-message configuration. Editing a key's configuration takes effect on new messages within a few seconds; you do not need to reconnect or restart your client.

A full session

On port 465 the client opens the TLS connection first, then runs the whole SMTP dialogue inside it:

Przykład kodu

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Bird
C: EHLO myapp
S: 250-eu1.smtp.bird.com
   250-SIZE 20971520
   250-8BITMIME
   250 AUTH PLAIN LOGIN
C: AUTH PLAIN <base64 bird + key>
S: 235 2.7.0 Authentication successful
C: MAIL FROM:<news@acme.com>
C: RCPT TO:<alice@example.com>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_019c1930687b7bfa8a1b2c3d4e5f6789

On port 587 or 2525 the client connects in plaintext, issues STARTTLS to upgrade the connection, then runs the same dialogue inside TLS. AUTH is not offered until the upgrade completes:

Przykład kodu

S: 220 eu1.smtp.bird.com ESMTP Bird
C: EHLO myapp
S: 250-eu1.smtp.bird.com
   250-SIZE 20971520
   250 STARTTLS
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-eu1.smtp.bird.com
   250-SIZE 20971520
   250 AUTH PLAIN LOGIN
C: AUTH PLAIN <base64 bird + key>
S: 235 2.7.0 Authentication successful
C: MAIL FROM:<news@acme.com>
C: RCPT TO:<alice@example.com>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_019c1930687b7bfa8a1b2c3d4e5f6789

The 250 response returns the queued message's id, the same em_… id you would get from the API. You can look the message up by that id in the Email log.

Retrying safely

The pipeline accepts a message and delivers it asynchronously, and SMTP clients retry aggressively when a connection drops. To make a retry safe, add an X-Bird-Idempotency-Key header to the message: a repeat within the retention window returns the id of the message that was already queued instead of sending a second copy. Use a value that is stable for the logical message, like an order id or a notification id, not a random one per attempt.

What comes back

SMTP rejects synchronously everything the API rejects. An unverified sending domain, a recipient on a reserved domain, an unusable IP pool, a malformed message, or an exceeded quota each come back as an SMTP error at the point the problem is detected, so a misconfigured send fails fast rather than disappearing. Suppressed recipients are the one exception. As with every provider, the message is accepted and the suppressed recipient is dropped downstream, visible in the Email log and events rather than as an SMTP error.

Next steps

Sending domains — verify the domain you'll send from.
Dedicated IPs & pools — choose which pool a key sends from.
Suppressions — why an accepted recipient might not receive a message.
Email log — find a message by the id SMTP returned.