Sending Emails

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:

• Plain Text Emails

• HTML Emails

• Sending to Multiple Recipients

• HTML metadata

• Emails with Attachments

• Emails with Inline Images

• Emails Using Templates

• Setting use case

• Emails with message tags

Send a message

Send a message to a channel

post

/workspaces/{workspaceId}/channels/{channelId}/messages

Authorizations

useraccessKey

Path parameters

workspaceIdstring · uuidrequired

The ID of the workspace

channelIdstring · uuidrequired

The ID for a channel

Body

all of

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/channels/{channelId}/messages' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{
    "sender": {
      "connector": {
        "identifierValue": "[e-mail]",
        "annotations": {
          "name": "text"
        }
      }
    },
    "receiver": {
      "contacts": [
        {
          "id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
          "identifierKey": "emailaddress",
          "identifierValue": "[e-mail]",
          "platformAddress": "text",
          "platformAddressSelector": "text",
          "type": "cc",
          "identifiers": [
            {
              "identifierKey": "emailaddress",
              "identifierValue": "[e-mail]"
            }
          ]
        }
      ]
    },
    "reference": "my-own-identifier",
    "template": {
      "name": "text",
      "projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
      "version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
      "locale": "text",
      "parameters": [
        {
          "key": "text",
          "value": "text",
          "type": "string"
        }
      ],
      "shortLinks": {
        "enabled": true,
        "domain": "text"
      },
      "variables": {
        "default": "text",
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true
        }
      ],
      "utmParameters": [
        {
          "key": "text",
          "value": "text"
        }
      ]
    },
    "meta": {
      "extraInformation": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "referral": {
        "source": "text",
        "title": "text",
        "text": "text",
        "group": "text",
        "metadata": {
          "source_id": "text",
          "source_url": "text",
          "media_url": "text",
          "tracking_id": "text"
        }
      },
      "order": {
        "products": [
          {
            "externalCatalogId": "text",
            "externalProductId": "text",
            "quantity": 1,
            "price": {
              "amount": 1,
              "exponent": 1,
              "currencyCode": "text"
            }
          }
        ]
      },
      "referredProduct": {
        "externalCatalogId": "text",
        "externalProductId": "text"
      },
      "email": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "from": {
          "username": "text",
          "displayName": "text"
        }
      },
      "pushNotifications": {
        "gatewayTypeOverride": "apns"
      },
      "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
      "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
      "flow": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "stepId": "text",
        "runId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "journey": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "stepId": "text",
        "runId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "campaign": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      }
    },
    "replyTo": {
      "id": "text",
      "order": 1,
      "type": "message"
    },
    "body": {
      "type": "text",
      "text": {
        "text": "text",
        "actions": [
          {
            "type": "link",
            "link": {
              "text": "text",
              "url": "text"
            }
          }
        ],
        "attachments": [
          {
            "mediaUrl": "https://example.com",
            "filename": "text",
            "inline": true
          }
        ],
        "metadata": {
          "subject": "text",
          "telegram": {
            "parseMode": "Markdown"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "whatsapp": {
            "previewUrl": true
          },
          "line": {
            "emoji": {
              "items": [
                {
                  "index": 1,
                  "productId": "text",
                  "emojiId": "text",
                  "length": 1
                }
              ]
            }
          }
        }
      }
    },
    "notification": {
      "url": "text"
    },
    "capFrequency": true,
    "enableLinkTracking": true,
    "ignoreQuietHours": true,
    "ignoreGlobalHoldout": true,
    "tags": [
      "text"
    ],
    "shortLinks": {
      "domain": "text"
    },
    "scheduledFor": "2025-02-28T01:54:42.520Z",
    "validity": 1
  }'

202

400

404

409

422

202

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "meta": {
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "source_id": "text",
        "source_url": "text",
        "media_url": "text",
        "tracking_id": "text"
      }
    },
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "quantity": 1,
          "price": {
            "amount": 1,
            "exponent": 1,
            "currencyCode": "text"
          }
        }
      ]
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "email": {
      "subject": "text",
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "pushNotifications": {
      "gatewayTypeOverride": "apns"
    },
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "stepId": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "stepId": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  },
  "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-28T01:54:42.520Z",
  "createdAt": "2025-02-28T01:54:42.520Z",
  "updatedAt": "2025-02-28T01:54:42.520Z",
  "details": "text",
  "failure": {
    "code": 1,
    "description": "Unsupported media type",
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2025-02-28T01:54:42.520Z",
  "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",
            "url": "text"
          }
        }
      ],
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true
        }
      ],
      "metadata": {
        "subject": "text",
        "telegram": {
          "parseMode": "Markdown"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text",
                "length": 1
              }
            ]
          }
        }
      }
    }
  }
}

Message was accepted for processing

Send a plain text email

To send a plain text email message with the above endpoint set the request body as follows:

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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.

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      },
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      },
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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. [e-mail]

• 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

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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:

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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:

<img src="cid:imagetext.png">

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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": "[e-mail]"
        },
        "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:

1. First make sure that the template is active.

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

3. Make sure that the variable names in your request match the variable names in the created template.

4. You can also add attachments to your template messages by adding an attachment array.

For example:

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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.

• transactional

• otp

• conversation

• marketing

curl --location '/workspaces/:workspaceID/channels/:channelID/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--data-raw '{
  "receiver": {
    "contacts": [
      {
          "identifierKey" : "emailaddress",
          "identifierValue": "[e-mail]"
      }
    ]
  },
  "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.

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"]
}'