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
  • 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

Was this helpful?

  1. Email API

Transmissions

Last updated 1 month ago

Was this helpful?

The Transmissions endpoint lets you send email. Each transmission can send an email to a single recipient or thousands. Reach Email API generates and sends messages using the options you've defined, a list of recipients, and the content given in transmissions call.

When creating a transmission, the options allow you to configure engagement tracking, sending optimization, global substitution data, and more to control how your emails are sent.

To set the recipients you can include all recipients in the request or use a stored recipient list. For each recipient, you can specify metadata and substitution data to personalize each email. You can also set the transmission to treat certain recipients as CC'd or BCC'd.

The content of the messages can be set in 4 different ways: inline content, a stored template, an A/B test, or raw RFC822 content. Each method has different use cases they are best suited for. All of these types of content can use the substitution data and metadata to create a unique message for each recipient.

Delete Scheduled Transmissions By Campaign ID

delete

Delete all scheduled transmissions in a campaign. The deletion process happens asynchronously in the background.

Notes:

  • Returns 204 immediately and processes deletion in background
  • When a message is deleted, a bounce event is generated with reason "554 5.7.1 [internal] Campaign cancelled"
  • Events can be tracked via Events API and Event Webhooks
  • Statistics available via Metrics API
  • For subaccount transmissions, request must be made as the subaccount
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters
campaign_idstringRequired

ID of the campaign to delete scheduled transmissions from

Example: christmas_campaign
Responses
204
Scheduled transmissions deletion initiated successfully
429
Rate limit exceeded
application/json
delete
DELETE /api/workspaces/{workspaceId}/reach/transmissions HTTP/1.1
Host: email.eu-west-1.api.bird.com
Accept: */*

No content

  • POSTCreate a Transmission
  • DELETEDelete Scheduled Transmissions By Campaign ID

Create a Transmission

post

Create a new email transmission. A transmission is a collection of recipients and email content.

Note: The transmission content (text + html + attachments + inline images) is limited to 20 MBs.

Sending Modes:

  • Using stored templates (recommended)
  • Using inline content
  • Using RFC822 content
  • Using A/B test
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters
num_rcpt_errorsintegerOptional

Maximum number of recipient errors to return

Default: 1
Body
recipientsone ofRequired

Recipients of the transmission. Can be an array of recipients or a stored recipient list.

or
contentone ofRequired

Content used to generate the messages. Must be one of: inline content, stored template, A/B test, or RFC822 content

or
or
or
campaign_idstring · max: 64Optional

Name of the campaign

Example: christmas_campaign
metadataobjectOptional

Transmission level metadata. Metadata is available in Webhook events and can also be used in the template language. Recipient metadata takes precedence over transmission metadata. Maximum length - 10KB.

descriptionstring · max: 1024Optional

Description of the transmission

Example: Christmas Campaign Email
substitution_dataobjectOptional

Key/value pairs that are provided to the substitution engine. Recipient substitution data takes precedence over transmission substitution data. Maximum length - 100KB.

Example: {"sender":"Big Store Team","holiday_name":"Christmas"}
Responses
200
Transmission created successfully
application/json
400
Request validation error
application/json
420
Sending limit exceeded
application/json
422
Unprocessable Entity
application/json
post
POST /api/workspaces/{workspaceId}/reach/transmissions HTTP/1.1
Host: email.eu-west-1.api.bird.com
Content-Type: application/json
Accept: */*
Content-Length: 1281

{
  "options": {
    "start_time": "2025-05-13T14:52:10.313Z",
    "open_tracking": true,
    "initial_open": true,
    "click_tracking": true,
    "transactional": true,
    "sandbox": true,
    "skip_suppression": true,
    "ip_pool": "marketing_ip_pool",
    "inline_css": true,
    "perform_substitutions": true
  },
  "recipients": [
    {
      "address": {
        "email": "wilma@flintstone.com",
        "name": "Wilma Flintstone"
      },
      "tags": [
        "prehistoric"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "customer_type": "Platinum",
        "year": "Freshman"
      },
      "return_path": "name@gmail.com",
      "rcpt_type": "to"
    }
  ],
  "content": {
    "from": "deals@example.com",
    "subject": "Big Christmas savings!",
    "text": "Hi {{address.name}}\nSave big this Christmas in your area!",
    "html": "<p>Hi {{address.name}}</p><p>Save big this Christmas in your area!</p>",
    "amp_html": "text",
    "reply_to": "Christmas Sales <sales@flintstone.com>",
    "headers": {
      "X-Customer-Campaign-ID": "christmas_campaign"
    },
    "attachments": [
      {
        "name": "billing.pdf",
        "type": "application/pdf",
        "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
      }
    ],
    "inline_images": [
      {
        "name": "my_image.jpeg",
        "type": "image/jpeg",
        "data": "VGhpcyBkb2Vzbid0IGxvb2sgbGlrZSBhIGpwZWcgdG8gbWUh"
      }
    ]
  },
  "campaign_id": "christmas_campaign",
  "metadata": {},
  "description": "Christmas Campaign Email",
  "substitution_data": {
    "sender": "Big Store Team",
    "holiday_name": "Christmas"
  }
}
{
  "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 1,
    "id": "11668787484950529"
  },
  "errors": [
    {
      "message": "transmission created, but with validation errors",
      "code": "2000",
      "description": "text",
      "rcpt_to_errors": [
        {
          "message": "required field is missing",
          "description": "address.email is required for each recipient",
          "code": "1400"
        }
      ]
    }
  ]
}