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

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

post

HTTPcURLJavaScriptPython

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-04-26T10:50:32.222Z",
    "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": "[e-mail]",
        "name": "Wilma Flintstone"
      },
      "tags": [
        "prehistoric"
      ],
      "metadata": {
        "age": "24",
        "place": "Bedrock"
      },
      "substitution_data": {
        "customer_type": "Platinum",
        "year": "Freshman"
      },
      "return_path": "[e-mail]",
      "rcpt_type": "to"
    }
  ],
  "content": {
    "from": "[e-mail]",
    "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 <[e-mail]>",
    "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

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

delete

HTTPcURLJavaScriptPython

DELETE /api/workspaces/{workspaceId}/reach/transmissions HTTP/1.1
Host: email.eu-west-1.api.bird.com
Accept: */*

No content