Documentation
Sign inGet started
शुरू करें
गाइड
API Reference
SDKs
CLI
Knowledge Base
Changelog

Send email over SMTP

If your application already supports SMTP, point it at our relay by changing its host, port, and credentials. Frameworks, content-management systems, printers, and other software that can submit mail to an SMTP relay can use this path.
Mail submitted over SMTP is treated exactly like mail sent through the email API: the same domain verification, IP pools, DKIM signing, suppression handling, tracking, events, and analytics. SMTP is a second way in to the same product, so everything you set up for one applies to the other.

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 API keys and does not require a separate SMTP credential. Create a key in Developers > API keys with email sending enabled. 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. Authenticating with a key from the other region fails with a 535 reply naming the host to use instead.
RegionHost
EUeu1.smtp.bird.com
USus1.smtp.bird.com
PortEncryption
465Implicit TLS (SMTPS)
587STARTTLS
2525STARTTLS
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" option, sometimes labeled plainly "TLS". 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 AUTH is refused 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:
कोड उदाहरण
Username: bird
Password: bk_eu1_your_api_key
The username is a fixed literal and has no identity of its own. 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. Revoking the key cuts off its SMTP sending within seconds, mid-connection included.

What comes from the message, and what comes from the key's configuration

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.
Send options that do not have a standard place in a MIME message come from the key's SMTP configuration. These include the IP pool, category, tags, and open and click tracking. An unconfigured key uses your organization's default pool, the transactional category, and tracking enabled. Configure the key in Email > SMTP, or call the SMTP config API. Give each application its own key when it needs different defaults. Changes apply to new messages without reconnecting the client.

A full session

On port 465 the client opens the TLS connection first, then runs the whole SMTP dialogue inside it:
कोड उदाहरण
   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0
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:
कोड उदाहरण
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0
The final 250 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 or through GET /v1/email/messages/{message_id}.

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, such as an order ID or notification ID. Avoid generating a random value for each attempt.

Connection limits

Each organization can hold up to 10 concurrent authenticated SMTP connections by default. A connection counts from authentication until it closes, across every server and API key in the organization. At the limit, another connection receives a transient 421 response after authentication. Reuse connections, reduce concurrency, and retry. The limit counts open connections independently of message volume. Email > SMTP shows live connections against the limit.

Handle SMTP responses

SMTP reports an unverified sending domain, reserved recipient domain, unusable IP pool, blocked attachment type, or malformed message with a permanent 550 response. A message over the 20 MB cap returns 552. An exceeded send quota or recipient count over 50 returns a transient 452. Suppressed recipients are handled asynchronously: SMTP accepts the message, then each suppressed recipient appears as rejected in the email log and events.

Next steps