In order to send an Email message, you must have an active Email channel and perform a HTTP request to the following endpoint with a valid access key .
Examples:
Send a message Send a message to a channel
post
/workspaces/{workspaceId} /channels/{channelId} /messages
workspaceId string uuid required
channelId string uuid required
reference string
A reference to the message. This can be used to identify the message in the channel.
Example: my-own-identifier
notification ChannelNotification
Show child attributes
tags string[]
Tags to associate with the message. Tags are converted to lower case and tags
that do not exist are automatically created. You can view your created tags
in the UI. You can specify up to 10 tags per message.
Show child attributes
shortLinks nullable object
SMS link shortening options. When using templates, please refer to
the template level shortLinks
instead.
Show child attributes
scheduledFor string date-time
Scheduled time to send message at. Must be formated as RFC3339 timestamp. When
set, the message status will be scheduled
until it's sent. Messages scheduled
for a time in the past or within 10 minutes of the request may be sent
immediately. Messages scheduled farther than 35 days will be rejected.
validity integer
Validity determines for how many seconds a message is valid. If none is provided, the channel message type will be used to determine it.
A promotional, conversational or transactional channel message is valid for 36 hours (129600 seconds). A message sent from a 2FA channel is valid for 10 minutes (600 seconds).
capFrequency boolean
If set to true, the frequency capping settings of the platform will be used
to either allow or reject the message to a contact. Can only be set to true
if the message is sent to a contact and .meta.extraInformation.useCase
is marketing
.
enableLinkTracking boolean
If set to true and message is a test/campaign message, web tracking parameters will be appended to the links in the message.
ignoreQuietHours boolean
If set to true, quiet hours settings will be ignored and the message will be sent as soon as possible.
ignoreGlobalHoldout boolean
Do not check if the recipient is part of global holdout. To be used to send transactional messages.
Show child attributes
Show child attributes
Copy curl -L \
--request POST \
--url '/workspaces/{workspaceId}/channels/{channelId}/messages' \
--header 'Authorization: Bearer jwt' \
--header 'Content-Type: application/json' \
--data '{"sender":{"connector":{"annotations":{},"identifierValue":"channels@bird.com"}},"receiver":{"contacts":[{"id":"a1405560-c8d3-4b1a-877d-3f449ad95352","identifierKey":"emailaddress","identifierValue":"channels@bird.com","type":"cc","identifiers":[{"identifierKey":"emailaddress","identifierValue":"channels@bird.com"}]}]},"reference":"my-own-identifier","template":{"projectId":"a1405560-c8d3-4b1a-877d-3f449ad95352","version":"a1405560-c8d3-4b1a-877d-3f449ad95352","parameters":[{"key":"text","type":"string"}],"variables":{},"shortLinks":{},"attachments":[{"mediaUrl":"https://example.com","filename":"text"}],"utmParameters":[{"key":"text","value":"text"}]},"meta":{"referral":{"metadata":{}},"order":{"products":[{"price":{}}]},"referredProduct":{},"email":{"headers":{},"from":{}},"pushNotifications":{"gatewayTypeOverride":"apns"},"flow":{},"journey":{},"campaign":{},"extraInformation":{"ANY_ADDITIONAL_PROPERTY":"anything"}},"replyTo":{"id":"text","type":"message"},"body":{"type":"text","text":{"text":"text","actions":[{"type":"link","link":{"text":"text"}}],"attachments":[{"mediaUrl":"https://example.com","filename":"text"}],"metadata":{"telegram":{"parseMode":"Markdown"},"headers":{},"whatsapp":{},"line":{"emoji":{"items":[{"index":1,"productId":"text","emojiId":"text"}]}}}}},"notification":{},"tags":[null],"shortLinks":{"domain":"text"}}'
Copy {
"id": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"meta": {
"referral": {
"metadata": {}
},
"order": {
"products": [
{
"price": {}
}
]
},
"referredProduct": {},
"email": {
"headers": {},
"from": {}
},
"pushNotifications": {
"gatewayTypeOverride": "apns"
},
"navigatorId": "123e4567-e89b-12d3-a456-426614174000",
"navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
"flow": {},
"journey": {},
"campaign": {},
"extraInformation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"reference": "my-own-identifier",
"parts": [
{
"platformReference": "text"
}
],
"status": "accepted",
"reason": "text",
"direction": "incoming",
"origin": {
"type": "text",
"id": "text"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"lastStatusAt": "2025-02-16T20:58:46.649Z",
"createdAt": "2025-02-16T20:58:46.649Z",
"updatedAt": "2025-02-16T20:58:46.649Z",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-02-16T20:58:46.649Z",
"details": "text",
"sender": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"body": {
"type": "text",
"text": {
"text": "text",
"actions": [
{
"type": "link",
"link": {
"text": "text"
}
}
],
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text"
}
],
"metadata": {
"telegram": {
"parseMode": "Markdown"
},
"headers": {},
"whatsapp": {},
"line": {
"emoji": {
"items": [
{
"index": 1,
"productId": "text",
"emojiId": "text"
}
]
}
}
}
}
}
}
Send a plain text email
To send a plain text email message with the above endpoint set the request body as follows:
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Single text message"
}
}
}'
Send an html email
To send an html email message with the above endpoint, set the request body as follows.
For email clients that do not support html and rich content set the plain text fallback field.
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"body": {
"type": "html",
"html": {
"html": "<div><h1>Hey, this is a nice html email.</h1></div>"
}
}
}'
Send an email to multiple participants
To send an email to multiple participants, add another object to the contacts array. Use the type field to specify if the recipient of the email should be on the To list, in CC , or BCC
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user1@example.com"
},
{
"identifierKey" : "emailaddress",
"identifierValue": "user2@example.com"
},
{
"identifierKey" : "emailaddress",
"identifierValue": "user3@example.com"
}
]
},
"body": {
"type": "html",
"html": {
"html": "<div><h1>Hey, this is a nice html email to multiple recipients.</h1></div>"
}
}
}'
HTML metadata
Within the HTML body object you can include a metdata object as follows:
body.metadata.html.subject = set the email subject
body.metadata.emailfrom.username = set the sender before the @ e.g. support @acme.com
body.metadata.emailfrom.displayname = set the display name appearing in users inbox e.g. Support team
body.metadata.headers.reply-to = the reply-to address
Set the email subject
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Hey, this is a nice text email.",
"metadata": {
"subject": "What is the subject?"
}
}
}
}'
Send a html message with attachments
To send an email with attached media, ensure that your media file is either publicly available or see uploading media .
Add attachment objects to body.text.attachments[]
or body.html.attachments[]
as shown. Each attachment object has the following properties:
mediaUrl = The URL location of the media
filename = The name of the file
inline = boolean (default false).
See sending inline images :
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Hey, this is a nice text email.",
"attachments": [
{
"mediaUrl": "https://docs.bird.com/~gitbook/image?url=https%3A%2F%2F3210271997-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdnJZeZvhOMhDQA8SpjQM%252Flogo%252FDR12k6Q9swjRC5qGPMFM%252FFrame%252071487.png%3Falt%3Dmedia%26token%3D81a28146-ce23-466b-84b2-3eca81168d86&width=128&dpr=3&quality=100&sign=d231cba2&sv=1",
"filename": "bird.png"
}
]
}
}
}'
Send an html message with inline images
To send an email with images inline, ensure that your media file is either publicly available or see uploading media .
Add an array of attachments to body.html
as above, but set body.html.attachments[].inline
to true.
Within body.html
reference the image in an image tag and prefix the filename with cid:
For example:
Copy <img src="cid:imagetext.png">
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"body": {
"type": "html",
"html": {
"text": "Single text message",
"html": "<p style=\"\">Single html message</p><p style=\"\"></p><p style=\"\"><p>INLINE IMAGE! <img src=\"cid:image.png\"></p>",
"metadata": {
"subject": "Here is an Email with an attachment",
"headers": {
"reply-to": "replyto@this.address"
},
"emailFrom": {
"username": "support",
"displayName": "Support Team"
}
},
"attachments": [
{
"mediaUrl": "mediaurl",
"filename": "image.png",
"inline": true
}
]
}
}
}'
Send a message with a template
Using Studio, you can create templates that can be reused across multiple email messages.
To use a template in a message:
First make sure that the template is active.
Then, specify the template details in the template
field of the request body, including the projectId
, version
, locale
, and any variables
that are present in the template.
Make sure that the variable names in your request match the variable names in the created template.
You can also add attachments to your template messages by adding an attachment array.
For example:
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"template": {
"locale": "en",
"projectId": ":projectID",
"version": ":versionID",
"attachments": [
{
"mediaUrl": "https://api.bird.com/bird.png",
"filename": "bird.png"
}
]
}
}'
Send a message specifying the use case
The example describes the request body to send an email with custom use case types. The default type is marketing, but you can specify others listed.
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"identifierKey" : "emailaddress",
"identifierValue": "user@example.com"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Hey, this is a nice text email."
}
},
"meta": {
"extraInformation": {
"useCase": "transactional"
}
}
}'
Send a message with tags
This example describes the request body to send an email with tags.
Copy curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
"receiver": {
"contacts": [
{
"id": ":contactID"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Hey, this is a nice text email."
}
},
"tags": ["tag-1", "tag-2"]
}'
Last updated 2 months ago