LogoLogo
No-code docsResources
  • 🖥️Welcome to the Bird API Docs
  • API Access
    • Access Policies
    • Access Roles
    • API Authorization
    • Common API usage
  • Conversations API
    • API reference
      • Channel configuration
        • Get conversations configuration
        • Update conversations configuration
      • Conversations messaging
        • Create conversation message
        • List conversation messages
        • Get conversation message
        • Update conversation message
        • Delete conversation message
        • Create pre-signed upload
      • Conversations management
        • Create conversation
        • List conversations
        • Get conversation
        • Update conversation
        • Delete conversation
      • Conversation Participants
        • Add participant to conversation
        • List participants
        • Get participant by ID
        • Get participant by identifier key and value
        • Update participant by ID
        • Update participant by identifier key and value
        • Delete participant
        • List participant conversations by ID
        • List participant conversations by identifier key and value
      • Workspace settings
        • Get antispam setting
        • Update antispam setting
        • Create allow/block rule
        • Get allow/block rule
        • List allow/block rules
        • Update allow/block rule
        • Delete allow/block rule
        • Add allow/block rules in bulk
        • Get allow/block bulk upload status
      • Events
  • Collaborations API
    • API reference
      • Agent Management
      • Team Management
      • Feeds
      • Feed item activity
      • Tags
      • Automation Rules
      • Business Hours
      • Capacity Rules
      • Routing Queues
      • Skills
      • SLA Policies
      • Macros
      • Sender Profiles
      • Ticket fields
  • Channels API
    • Supported channels
      • Programmable WhatsApp
        • Sending WhatsApp messages
        • Customer service window
        • Receiving messages
        • Message interactions
        • WhatsApp ISV integration
          • Setting up your customer workspaces
            • API Access
            • Associating your Facebook solution ID and business ID with your Bird CRM Organization
            • Creating a workspace for your customer
            • Buying a number through Bird
            • Subscribing to channel created webhooks
          • WhatsApp channel onboarding
            • Setting up the WhatsApp Embedded flow
            • Install WhatsApp phone number in Bird CRM
            • Subscribe to channel webhooks
      • Programmable SMS
        • Installing an SMS channel
          • US 10DLC API Installation
          • Toll-Free Numbers Verification API
        • Sending SMS messages
        • Receiving messages
        • Twilio Exit API
          • Using Twilio PHP SDK
          • Using Twilio Go SDK
          • Using Twilio Ruby SDK
        • Sinch Exit API
      • Programmable RCS
        • Sending messages
        • Receiving messages
        • Message interactions
      • Programmable Email
        • Sending Emails
        • Receiving messages
        • Message status
        • Message interactions
      • Programmable Line
        • Sending messages
        • Receiving messages
        • Message interactions
      • Programmable Telegram
        • Sending messages
        • Receiving messages
        • Message interactions
    • Message types
      • Text
      • Images
      • Files
      • List
      • Carousel
      • Template
    • Message status and interactions
      • Message Failure Codes
      • Message Failure Sources
        • SMS Platform Extended Error Codes
    • Send batch messages
    • API reference
      • Channel Groups
      • Messaging
      • Channels management
      • Channel connectors
      • Navigators
      • Compliance Keywords Messages
      • Conversions Sharing
      • Events
    • Rate Limit
  • Voice API
    • Installing a Voice channel
    • Voice Calls API
      • Initiate an outbound call
      • List calls from a channel
      • Get a call
      • Update a call
      • Answer a call
      • Ring a call
      • Hangup a call
      • Play a message in a call
      • Say Text-To-Speech (TTS)
      • Gather DTMF from a call
      • Forward a call
      • Record a Call
      • Record a call session
      • Update a call recording
      • List call recordings of a call
      • Get a call recording
      • Get a call insights
      • Get calls log
    • Recordings API
      • List Recordings
      • Get a Recording
      • Delete a Recording
      • List recording storage metrics
    • Transcriptions API
      • Initiate a Transcription
      • List Transcriptions
      • Get a Transcription
      • Delete a Transcription
    • Voice webhooks
    • Flash Calling API
  • Verify API
    • Verify API: Quick Start
  • Contacts API
    • Tracking Contact Events
      • API Reference
        • Get configuration
        • Track events
    • API reference
      • Manage workspace contacts
        • Create a contact
        • Get a contact
        • List contacts
        • Search contact by identifier
        • Update a contact
        • Create or update a contact by identifier
        • Delete a contact
      • Manage contact identifiers
        • Create contact identifier
        • List contact identifiers
        • Delete contact identifier
      • Manage contact attribute definition
        • Create attribute definition
        • Get attribute definition
        • List attribute definitions
      • Manage contact lists
        • Create a list
        • Get a list
        • List lists
        • Update a list
        • Delete a list
        • Add contacts to a list
        • Get contact list memberships
        • List contacts in a list
        • Remove contacts from a list
      • Lookup
        • Network/Country information for a phone number
  • Numbers API
    • API reference
      • Search Available Numbers
      • Buy a Number
      • List your Numbers
      • Get Long Code Number Details
      • Manage Endpoint Subscriptions
        • Cancel Number Subscription
      • Manage Endpoint Compliance Requirements
        • List Workspace compliace Requirements
        • Get Workspace Compliace Requirements
        • Update Workspace Compliace Requirements
      • 10DLC Compliance
        • Brands - Organization
          • Create a brand
          • List all brands
          • Get a brand
          • Update a brand
          • Delete a brand
          • Create a brand vetting
        • Brands - workspace
          • Create a brand
          • List all brands
          • Get a brand
          • Update a brand
          • Delete a brand
          • Create a brand vetting
          • List brand vettings
        • Campaigns
          • Optional: acting as Reseller
          • Create a campaign
          • List all campaigns
          • Get a campaign
          • Update a campaign
          • Delete a campaign
        • TCR Enums
        • Events
      • Toll-Free Numbers Verification API
      • Long Code Numbers
      • Short Code Numbers
      • Alphanumeric Senders
      • Events
  • Know-Your-Customer (KYC) API
    • List KYC forms
    • Get KYC form
    • Create KYC form entry
    • Update KYC form entry
    • List KYC form entries
    • Get a KYC form entry details
  • Reporting API
    • API reference
      • Channel Metrics
      • Flow Run Metrics
      • Wallet Metrics
      • Campaign Metrics
      • Message Metrics
  • Accounts API
    • API reference
      • Current user
        • Change password
        • Presigned upload
        • Memberships
        • Sessions
        • Configurations
          • Groups
            • Keys
      • IAM policies
      • Organizations
        • Upload media
        • Profile
        • Workspaces
        • Users
        • Access keys
        • Organization roles
        • Organization policies
        • Teams
          • Members
        • Approvals
          • Runs
            • Reviews
        • Configurations
          • Groups
            • Keys
      • Region groups
  • Touchpoints API
    • Supported Projects
      • Whatsapp Approved Message Templates
        • Creating WhatsApp Message templates
          • Text template blocks
          • Blocks Documentation
    • API reference
      • Projects
      • Message Templates
  • Notifications API
    • API Reference
      • Webhook subscriptions
        • Create a webhook subscription
        • List available webhook events
        • Get a webhook subscription
        • List webhook subscriptions
        • Update a webhook subscription
        • Delete a webhook subscription
        • Verifying a webhook subscription
        • Webhook subscription logs
  • Knowledge Base (KB) API
    • API reference
      • Documents
      • Folders
        • Import
      • Search
      • Presigned upload
  • Email API
    • Transmissions
    • Metrics
    • Events
    • Recipient Validation
    • Webhooks
    • SMTP API
  • Connectivity platform migration guide
    • Channels API and Conversations API
    • Migrating conversations API actions
    • Migrating WhatsApp channels
  • Client SDKs
    • Applications
    • Contact Profiles
      • Signed Identity
    • Push notifications
      • Quick Start
      • Subscribe contacts to push notification campaigns
      • Notification Display Priority
    • Event Tracking
      • Quick Start
      • Track Events
        • App
        • Audiences
        • Conference
        • Ecommerce
        • Hospitality
        • Lists
        • Messaging
        • Payments
        • Subscription
        • Suppressions
        • Survey
        • Web
    • App Inbox
      • Quick Start
      • Usage
      • Subscribe contacts to app inbox campaigns
    • SDK Integration
      • Android SDK
        • Notification Interactions
      • Swift SDK
        • Notification Interactions
      • Web SDK
        • Quick Start
        • Usage
        • API Reference
          • IdentityManager
          • BirdSdkApi
          • BirdTracker
            • Ecommerce
            • Conference
            • Messaging
            • Suppressions
            • Subscription
            • Survey
            • Web
            • Audiences
        • Web Push Notifications
          • Notification Interactions
  • Quickstarts
    • Conversations
    • Send an SMS message
    • Send an Email message
    • Send a WhatsApp message
Powered by GitBook
On this page
  • SMTP API
  • Client Configuration
  • SMTP Security
  • Using The X-MSYS-API Custom Header
  • The Sandbox Domain
  • Sending Messages with cc, bcc, and archive Recipients
  • Comments on Header Length
  • Non-ASCII characters
  • Invalid JSON
  • SMTP MAIL FROM
  • AMPHTML Email

Was this helpful?

  1. Email API

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

smtp.email.us-west-2.api.bird.com smtp.email.eu-west-1.api.bird.com for EU workspaces

Use the host located where the workspace and access key were created.

Port

587 or 2525

Port 2525 is provided as an alternate port for cases where port 587 is blocked (such as a Google Compute Engine environment).

Encryption

STARTTLS

Authentication

AUTH LOGIN

User

SMTP_Injection:x-bird-workspace-id={workspaceId}

Replace {workspaceId} with your workspace ID

Password

AccessKey {reachAccessKey}

Per-command Timeout

Minimum 60 seconds

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"}

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

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

5.6.0 X-MSYS-API 'metadata' must be of type 'json object' 5.6.0 smtpapi_campaign_id context is limited to 64 bytes

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.

Last updated 1 month ago

Was this helpful?

Replace {reachAccessKey} with An API key with "Reach Email Admin" permission. You can create and manage your API Keys from the .

See for RFC recommended values.

When the X-MSYS-API header is unfolded on the receiving system, as per , a single space will be added between each line of the header.

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 -encoded.

RFC2822
rfc2047
app
RFC-5321