Transmissions

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 2 different ways: inline content or raw RFC822 content. Each method is best suited for different use cases. All of these types of content can use the substitution data and metadata to create a unique message for each recipient.

Regional Endpoints

Please use the appropriate API endpoint based on your workspace region:

• EU workspaces: https://email.eu-west-1.api.bird.com

• US workspaces: https://email.us-west-2.api.bird.com

Create a Transmission

post

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/transmissions

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 inline content

• Using RFC822 content

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

num_rcpt_errorsintegerOptional

Maximum number of recipient errors to return

Default: 1

Body

application/json

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 or RFC822 content

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

/workspaces/{workspaceId}/reach/transmissions

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/transmissions HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1285

{
  "options": {
    "start_time": "2026-01-30T08:14:53.099Z",
    "open_tracking": true,
    "initial_open": true,
    "click_tracking": true,
    "transactional": false,
    "sandbox": false,
    "skip_suppression": false,
    "ip_pool": "marketing_ip_pool",
    "inline_css": false,
    "perform_substitutions": true
  },
  "recipients": [
    {
      "address": {
        "email": "[email protected]",
        "name": "Wilma Flintstone"
      },
      "tags": [
        "prehistoric"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "customer_type": "Platinum",
        "year": "Freshman"
      },
      "return_path": "[email protected]",
      "rcpt_type": "to"
    }
  ],
  "content": {
    "from": "[email protected]",
    "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 <[email protected]>",
    "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"
        }
      ]
    }
  ]
}

Delete Scheduled Transmissions By Campaign ID

delete

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/transmissions

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

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

/workspaces/{workspaceId}/reach/transmissions

HTTPcURLJavaScriptPython

DELETE /api/workspaces/{workspaceId}/reach/transmissions?campaign_id=christmas_campaign HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

No content