# 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-1.api.bird.com>

## Create a Transmission

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

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Transmissions","description":"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.\n\nWhen 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.\n\nTo 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.\n\nThe 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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"TransmissionRequest":{"required":["content","recipients"],"type":"object","properties":{"options":{"$ref":"#/components/schemas/TransmissionOptions"},"recipients":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},{"$ref":"#/components/schemas/RecipientList"}],"description":"Recipients of the transmission. Can be an array of recipients or a stored recipient list."},"content":{"oneOf":[{"$ref":"#/components/schemas/InlineContent"},{"$ref":"#/components/schemas/RFC822Content"}],"description":"Content used to generate the messages. Must be one of: inline content or RFC822 content"},"campaign_id":{"type":"string","maxLength":64,"description":"Name of the campaign"},"metadata":{"type":"object","description":"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.","properties":{}},"description":{"type":"string","maxLength":1024,"description":"Description of the transmission"},"substitution_data":{"type":"object","description":"Key/value pairs that are provided to the substitution engine. Recipient substitution data takes precedence over transmission substitution data. Maximum length - 100KB."}}},"TransmissionOptions":{"type":"object","properties":{"start_time":{"type":"string","description":"The system will not attempt to deliver messages until this datetime.","format":"date-time"},"open_tracking":{"type":"boolean","description":"Enable or disable open tracking. If this option is not set, then the value of the `rest_tracking_default` account option is used. See the [Account API documentation](https://developers.sparkpost.com/api/account/#account-options) for more information on this account option."},"initial_open":{"type":"boolean","description":"Enable or disable initial open tracking. If this option is not set and `open_tracking` is `true`, then the value of the `initial_open_pixel_tracking` account option is used. If this option is not set and `open_tracking` is `false`, then this option is set to `false`. If neither this option nor the `open_tracking` option is set, then this value is set based on the `rest_tracking_default` and `initial_open_pixel_tracking` account options. See the [Account API documentation](https://developers.sparkpost.com/api/account/#account-options) for more information on these account options."},"click_tracking":{"type":"boolean","description":"Enable/disable click tracking","default":true},"transactional":{"type":"boolean","description":"Distinguish between *transactional* and *non-transactional* messages for unsubscribe and suppression purposes.","default":false},"sandbox":{"type":"boolean","description":"Whether to to use the sandbox sending domain.","default":false},"skip_suppression":{"type":"boolean","description":"Whether to ignore customer suppression rules. Enterprise only.","default":false},"ip_pool":{"type":"string","description":"The ID of a dedicated IP pool to send from. If this field is not provided, the account's default dedicated IP pool is used (if there are IPs assigned to it)."},"inline_css":{"type":"boolean","description":"Whether to inline the CSS in `<style>` tags in the `<head>` of the HTML content. Not performed on AMPHTML","default":false},"perform_substitutions":{"type":"boolean","description":"Enable or disable substitutions. Can only be set to `false` when using an inline template. Setting to `false` disables substitutions in the `text`, `html`, `amp`, and `email_rfc822` content parts and also disables all macros (including snippets). Headers are still passed to the substitution engine when this option is set to `false`. That includes headers that are part of `email_rfc822` content parts","default":true}}},"Recipient":{"required":["address"],"type":"object","properties":{"address":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Valid email address"},"name":{"type":"string","description":"Full name of the recipient"}}},"tags":{"type":"array","description":"Array of tags associated with this recipient","items":{"type":"string"}},"metadata":{"type":"object","properties":{},"description":"Metadata specific to this recipient. Takes precedence over transmission metadata."},"substitution_data":{"type":"object","properties":{},"description":"Substitution data specific to this recipient. Takes precedence over transmission substitution data."},"return_path":{"type":"string","description":"Email address to use for VERP (Variable Envelope Return Path).\nThe domain must be a CNAME-verified sending domain.\nEnterprise accounts can use any valid email address.\n","format":"email"},"rcpt_type":{"type":"string","description":"Type of recipient for CC/BCC support","default":"to","enum":["to","cc","bcc"]}}},"RecipientList":{"required":["list_id"],"type":"object","properties":{"list_id":{"type":"string","description":"ID of the stored recipient list to use"}}},"InlineContent":{"required":["from","subject"],"type":"object","properties":{"from":{"oneOf":[{"type":"string","format":"email","description":"Email address of the sender"},{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address of the sender"},"name":{"type":"string","description":"Display name of the sender"}}}],"description":"The domain must be a verified sending domain. Can be a string with a valid email address or an object with the attributes described."},"subject":{"type":"string","description":"Email subject line. Expected in UTF-8 charset without RFC2047 encoding."},"text":{"type":"string","description":"Text content for the email's text/plain MIME part.\nExpected in UTF-8 charset with no Content-Transfer-Encoding applied.\nAt least one of html or text is required.\n"},"html":{"type":"string","description":"HTML content for the email's text/html MIME part.\nExpected in UTF-8 charset with no Content-Transfer-Encoding applied.\nAt least one of html or text is required.\n"},"amp_html":{"type":"string","description":"AMPHTML Email content for the email's text/x-amp-html MIME part.\nAt least one of html or text must also be provided.\nExpected in UTF-8 charset with no Content-Transfer-Encoding applied.\n"},"reply_to":{"type":"string","description":"Email address used to compose the Reply-To header"},"headers":{"type":"object","properties":{},"description":"Object containing headers other than Subject, From, To, and Reply-To.\nHeaders such as Content-Type and Content-Transfer-Encoding are not allowed.\nEach header value is expected in UTF-8 charset without RFC2047 encoding.\nThe To header should not be specified as it is generated from each recipient's address field.\n"},"attachments":{"type":"array","description":"Array of attachments to include in the email","items":{"$ref":"#/components/schemas/Attachment"}},"inline_images":{"type":"array","description":"Array of inline images to include in the email","items":{"$ref":"#/components/schemas/InlineImage"}}}},"Attachment":{"required":["data","name","type"],"type":"object","properties":{"name":{"maxLength":255,"type":"string","description":"The filename of the attachment"},"type":{"type":"string","description":"The MIME type of the attachment.\nInclude the charset parameter if needed (e.g. `text/html; charset=\"UTF-8\"`)\n"},"data":{"type":"string","description":"The content of the attachment as a Base64 encoded string.\nShould not contain `\\r\\n` line breaks.\n"}}},"InlineImage":{"required":["data","name","type"],"type":"object","properties":{"name":{"maxLength":255,"type":"string","description":"The name of the image, which will be inserted into the Content-ID header.\nMust be unique within the inline_images array.\nReferenced in HTML using <img src=\"cid:NAME\" />\n"},"type":{"type":"string","description":"The MIME type of the image"},"data":{"type":"string","description":"The content of the image as a Base64 encoded string.\nShould not contain `\\r\\n` line breaks.\n"}}},"RFC822Content":{"required":["email_rfc822"],"type":"object","properties":{"email_rfc822":{"type":"string","description":"Pre-built message with the format as described by the message/rfc822 Content-Type.\n\n**Important Notes:**\n- Substitutions will be applied in the top-level headers and the first non-attachment text/plain, text/html, and text/x-amp-html MIME parts only\n- If text/x-amp-html is used, it must be a descendant of multipart/alternative, alongside at least one other text/html or text/plain MIME part\n- Lone LFs and lone CRs are allowed. Reach Email API converts line endings to CRLF where necessary\n- Should NOT be dot stuffed (Reach Email API handles this)\n- Should NOT contain the SMTP terminator `\\r\\n.\\r\\n` (Reach Email API adds this)\n- Content headers are not generated for RFC822 content. They must be provided in the RFC822 content\n"}}},"TransmissionResponse":{"type":"object","properties":{"results":{"required":["id","total_accepted_recipients","total_rejected_recipients"],"type":"object","properties":{"total_rejected_recipients":{"type":"integer","description":"Number of recipients that were rejected"},"total_accepted_recipients":{"type":"integer","description":"Number of recipients that were accepted"},"id":{"type":"string","description":"Unique identifier for this transmission"}}},"errors":{"type":"array","description":"Array of errors if any occurred during transmission creation","items":{"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"},"rcpt_to_errors":{"type":"array","description":"Array of recipient-specific errors","items":{"type":"object","properties":{"message":{"type":"string","description":"Error message for this recipient"},"description":{"type":"string","description":"Detailed description of the recipient error"},"code":{"type":"string","description":"Error code for this recipient"}}}}}}}}},"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/transmissions":{"post":{"tags":["Transmissions"],"summary":"Create a Transmission","description":"Create a new email transmission. A transmission is a collection of recipients and email content.\n\n**Note:** The transmission content (text + html + attachments + inline images) is limited to 20 MBs.\n\n**Sending Modes:**\n- Using inline content\n- Using RFC822 content\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"num_rcpt_errors","in":"query","description":"Maximum number of recipient errors to return","schema":{"type":"integer","default":1}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransmissionRequest"}}},"required":true},"responses":{"200":{"description":"Transmission created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransmissionResponse"}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"420":{"description":"Sending limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Delete Scheduled Transmissions By Campaign ID

> 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

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Transmissions","description":"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.\n\nWhen 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.\n\nTo 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.\n\nThe 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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"parameters":{"workspaceId":{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/transmissions":{"delete":{"tags":["Transmissions"],"summary":"Delete Scheduled Transmissions By Campaign ID","description":"Delete all scheduled transmissions in a campaign. The deletion process happens asynchronously in the background.\n\n**Notes:**\n- Returns 204 immediately and processes deletion in background\n- When a message is deleted, a bounce event is generated with reason \"554 5.7.1 [internal] Campaign cancelled\"\n- Events can be tracked via Events API and Event Webhooks\n- Statistics available via Metrics API\n- For subaccount transmissions, request must be made as the subaccount","parameters":[{"$ref":"#/components/parameters/workspaceId"},{"name":"campaign_id","in":"query","description":"ID of the campaign to delete scheduled transmissions from","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Scheduled transmissions deletion initiated successfully"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions: 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/transmissions.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.