> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/email-api/smtp-api.md).

# SMTP API

## SMTP API

The Bird SMTP API offers an SMTP relay service with extended features available through the `X-MSYS-API` custom header.

### Client Configuration

To use Bird as an SMTP relay you need to point your SMTP client or local MTA to the following endpoint:

| Name                | Value                                                                                                                     | Notes                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host                | <p><code>smtp.email.us-west-2.api.bird.com</code><br><code>smtp.email.eu-west-1.api.bird.com</code> for EU workspaces</p> | Use the host located where the workspace and access key were created.                                                                                         |
| Port                | `587` or `2525`                                                                                                           | <p>Port 2525 is provided as an alternate port for cases where port 587<br>is blocked (such as a Google Compute Engine environment).</p>                       |
| Encryption          | `STARTTLS`                                                                                                                |                                                                                                                                                               |
| Authentication      | `AUTH LOGIN`                                                                                                              |                                                                                                                                                               |
| User                | `SMTP_Injection:x-bird-workspace-id={workspaceId}`                                                                        | Replace `{workspaceId}` with your workspace ID                                                                                                                |
| Password            | `AccessKey {reachAccessKey}`                                                                                              | Replace `{reachAccessKey}` with An API key with "Reach Email Admin" permission. You can create and manage your API Keys from the [app](https://app.bird.com). |
| Per-command Timeout | Minimum 60 seconds                                                                                                        | See [RFC-5321](https://tools.ietf.org/html/rfc5321#section-4.5.3.2) for RFC recommended values.                                                               |

### SMTP Security

Disabling TLS will cause all data sent through Bird to be sent over the public internet unencrypted.

Bird strongly recommends using TLS with SMTP to protect your message content, recipient information and API keys in transmission. This includes API keys and any details such as recipient email addresses and message content.

Bird recommends reusing existing connections to inject up to 100 messages each. After injecting 100 messages, the client SHOULD disconnect and establish a new connection. Additionally, Bird will automatically disconnect idle connections after 1 minute.

It is also good practice to regularly cycle your API keys to limit exposure of keys sent in the clear.\
API keys should be treated like passwords.\
You are solely responsible for all use of \[your account].\
That includes use of your account with API key compromised on an unsecured connection.

### Using The X-MSYS-API Custom Header

You can use the `X-MSYS-API` header in your SMTP messages to specify a campaign id, metadata, tags, IP pool, CC, BCC, and archive recipient lists and disable open and/or click tracking.

To use this option you should be familiar with how to encode options as JSON strings, as the value of the header field is a JSON object that specifies the relevant options

```
X-MSYS-API: {
  "campaign_id": "my_campaign",
  "metadata" : {
    "has_pets": true,
    "pet_name": "Spot"
  },
  "cc": [
    { "email": "cc_recip_1@gmail.com", "name": "CC 1" },
    { "email": "cc_recip_2@gmail.com", "name": "CC 2" }
  ],
  "bcc": [
    { "email": "bcc_recip_1@gmail.com", "name": "BCC 1" }
    { "email": "bcc_recip_2@gmail.com", "name": "BCC 2" }
  ],
  "archive": [
    { "email": "archive_recip_1@gmail.com", "name": "Archive 1" }
    { "email": "archive_recip_2@gmail.com", "name": "Archive 2" }
  ],
  "tags": [
    "cat",
    "dog"
  ],
  "options" : {
    "open_tracking": false,
    "click_tracking": false,
    "transactional": false,
    "sandbox": false,
    "skip_suppression": false,
    "ip_pool": "my_ip_pool",
    "inline_css": false
  }
}
```

The template language is not supported in SMTP API. Any `substitution_data` field provided in the X-MSYS-API header will be ignored.

The fields supported in the X-MSYS-API header are as follows:

* Data Structure: X-MSYS-API Attributes
  * campaign\_id (string) - Name of the campaign to associate with the SMTP message\
    Maximum length: 64 bytes
  * metadata (object) - JSON key value pairs associated with the SMTP message\
    A maximum of 1000 bytes of metadata is available in click/open events.
  * cc (array) - Array of recipient addresses that will be included in the "Cc" header. A unique message with a unique tracking URL will be generated for each recipient in this list.
  * bcc (array) - Array of recipient addresses that will be hidden from all other recipients. A unique message with a unique tracking URL will be generated for each recipient in this list.
  * archive (array) - Array of recipient addresses that will be hidden from all other recipients. A unique message will be generated for each recipient in this list. The archive copy of the message contains tracking URLs identical to the recipient. For a full description, see What is an archive recipient? section.
  * tags (array) - Array of text labels associated with the SMTP message. Tags are available in click/open events. Maximum number of tags is 10 per recipient, 100 system wide.
  * options (object) - Object in which SMTP API options are defined.
    * open\_tracking (boolean) - Whether open tracking is enabled for this SMTP message See notes for defaults.
    * click\_tracking (boolean) - Whether click tracking is enabled for this SMTP message. See notes for defaults.
    * transactional (boolean) - Whether message is transactional, for unsubscribe and suppression purposes\
      **Note** no List-Unsubscribe header is included in transactional messages.
      * Default: false
    * sandbox (boolean) - Whether to use the sandbox sending domain.\
      Not available for **Enterprise** accounts.
      * Default: false
    * skip\_suppression (boolean) - Whether to ignore customer suppression rules, for this SMTP message only.\
      **Enterprise** Defaults to false.
    * ip\_pool (string) - The ID of a dedicated IP pool associated with your account. If this field is not provided, the account's default dedicated IP pool is used (if there are IPs assigned to it).\
      **Bird** For more information on dedicated IPs, contact support.
    * inline\_css (boolean) - Whether to inline the CSS in `<style>` tags in the `<head>` in the HTML content. Not performed on AMPHTML Email content.
      * Default: false

#### Open And Click Tracking

**Enterprise accounts:** SMTP click and open tracking are **enabled** by default. Please check with your TAM if you are unsure of the setting in your own environment.

SMTP click and open tracking are **disabled** by default. To enable click and open tracking in SMTP messages, add the X-MSYS-API header as follows:

```
X-MSYS-API: { "options" : { "open_tracking" : true, "click_tracking" : true } }
```

**Bird customers:** the `open_tracking` and `click_tracking` variables may also be set account-wide in your SMTP relay account settings.

### The Sandbox Domain

The Sandbox Domain is available to Bird customers only

The sandbox domain `birdemailbox.com` is available to allow each account to send test messages in advance of configuring a real sending domain. Each Bird account has a lifetime allowance of 5 sandbox domain messages. That means one may send up to 5 test messages using `From: something@birdemailbox.com`. Note that you can set the 'local part' (the part before the @) to any valid email local part.

### Sending Messages with cc, bcc, and archive Recipients

When submitting an email via SMTP that includes the X-MSYS-API header, you may specify a JSON array for cc, bcc, and archive lists. For each address in each of these arrays, a message will be generated. Messages will be generated with the following headers:

* It is the responsibility of the user to include their own `To` header in the body of the message.
* All messages will display the `Cc` header and the value of that header will include all addresses listed in the `cc` array.
* The `bcc` recipients will each receive a message with the `To` and `Cc` headers described above and, additionally, will see a `Bcc` header with ONLY their own recipient address as the value of the header.
* The `archive` recipients will each receive a message with the `To` and `Cc` headers described above however, they will not have a `Bcc` header.

The following are key points about reporting and tracking for cc, bcc, and archive messages:

* Each recipient (To, Cc, Bcc, and archive) is counted as a targeted message.
* A `rcpt_type` field is available during events through the Webhooks, which designates if the message was a Cc, Bcc, or archive copy.
* A `transmission_id` field is available during events through the Webhooks, which can be used to correlate the Cc, Bcc, and archive versions of the messages to one another.

Each recipient will only receive a single instance of each message, even if they appear on more than one of the CC, BCC or archive recipient lists.

**What is an archive recipient?**

Recipients in the `archive` list will receive an exact replica of the message that was sent to the RCPT TO address. In particular, any encoded links intended for the `RCPT TO` recipient will be identical in the archive messages. In contrast, recipients in the `bcc` list will have links encoded specific to their address. There will be some small differences between the `RCPT TO` message and the `archive` message, for example in headers that contain the delivery address like `X-MSFBL` and `List-Unsubscribe`.

For example:

```
X-MSYS-API: {
   "cc" : [ "cc_email1@corp.com", "cc_email2@corp.com" ],
   "bcc" : [ "bcc_email1@corp.com", "bcc_email2@corp.com" ],
   "archive" : [ "archive_email@corp.com" ],
   "options" : {"open_tracking" : false, "click_tracking" : true},
}
```

You may not specify more than a total of 1000 total recipients in those 3 lists.

You may also specify name and email keys in the `cc` and `bcc` JSON arrays in order to produce a friendly `Cc` or `Bcc` header. For example:

```
X-MSYS-API: {
   "cc" : [
    {
    "email" : "cc_recip_1@gmail.com",
    "name" : "CC 1"
    },
    {
    "email" : "cc_recip_2@gmail.com",
    "name" : "CC 2"
    }
  ]

  "bcc" : [
    {
    "email" : "bcc_recip_1@gmail.com",
    "name" : "BCC 1"
    }
  ]
}
```

### Comments on Header Length

SMTP defines a maximum line length of 1000 characters (including CRLF). If the value of the `X-MSYS-API` JSON string is\
longer than 998 characters, it will be folded across multiple lines before the message is injected. An example\
of a folded header that will not have issues due to extra spaces:

```
X-MSYS-API: {"options" : {"open_tracking" : false, "click_tracking" : true},
   "metadata" : {"has_pets" : true, "pet_name": "Spot" }, "tags" : ["cat",
   "dog"], "campaign_id" : "my_campaign"}
```

When the `X-MSYS-API` header is unfolded on the receiving system, as per [RFC2822](http://www.rfcreader.com/#rfc2822_line324), a single space will be added between each line of the header.

The following example shows how the JSON object in an `X-MSYS-API` header can be corrupted as a result of folding and unfolding:

```
X-MSYS-API: {"options" : {"open_tracking" : false }, "campaign_id" : "my_awes
   ome_campaign" }
```

Will be unfolded as

```
X-MSYS-API: {"options" : {"open_tracking" : false }, "campaign_id" : "my_awes ome_campaign" }
```

Note the space that was introduced in the `my_awes ome_campaign` string.

### Non-ASCII characters

If non-ASCII characters are present in the `campaign_id`, `tags`, or `metadata` fields, they must be escaped using the `\u` Unicode code point format ( becomes `\u000A`), or [rfc2047](http://www.rfcreader.com/#rfc2047)-encoded.

### Invalid JSON

If the `X-MSYS-API` header contains invalid JSON, the SMTP message will be rejected with one of the following codes:

| Code | Example                                                                                                                                                  |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 550  | <p><code>5.6.0 X-MSYS-API 'metadata' must be of type 'json object'</code><br><code>5.6.0 smtpapi\_campaign\_id context is limited to 64 bytes</code></p> |
| 421  | `4.3.3 [internal] smtpapi unable to generate unique transmission id`                                                                                     |

### SMTP MAIL FROM

In many cases the SMTP MAIL FROM (or "envelope from") address may be any email address. The address will be overwritten with a Bird specific email address before the email is delivered.\
If you would like Bird to deliver the email with a custom MAIL FROM domain then the domain specified in the MAIL FROM address must be set up ahead of time as a CNAME-verified sending domain.

**Note:** Bird will **not** overwrite the MAIL FROM address for **Enterprise** accounts.

### AMPHTML Email

AMPHTML Email content may be provided in a `text/x-amp-html` MIME part. `text/x-amp-html` must be a descendant of multipart/alternative, alongside at least one other `text/html` or `text/plain` MIME part.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/email-api/smtp-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.