Send an Email message

By following these instructions, you'll be able to setup an Email channel and use it to send messages through the API.

Step 1: Setup your API Key

In order to send messages through the API, you'll need an API key. Click the bottom left menu and then select User Settings.

Head to Security -> Access Keys -> Add new access key.

Create an access key with the role Application Developer.

Now you have an access key you'll be able to use when sending messages through the API.

Step 2: Create an email channel

In the top left menu, select Manage Channels -> Email.

Click Install Email and fill out the information about your email channel.

After creating your channel, you'll be presented with a few DNS records that need to be registered with your DNS provider. Once the DNS records are in place, click Verify domain at the bottom. You may need to retry this a few times due to DNS propagation times. If you're having difficulty with this step, check out the Troubleshooting section.

If everything worked, in the Health tab you should see a message saying your channel is healthy and ready to be used.

Lastly, take note of your channel ID in the settings tab, you'll need it when performing the API request.

Step 3: Check your workspace ID

The last thing we need to send messages is to know your workspace ID. In the bottom left menu, select User Settings and navigate to Organization -> Workspaces and then select your workspace, now you should be able to take note of your workspace ID.

Step 4: Send a message

Use the command below to perform a request that sends a message. You'll need to fill in your workspace ID, your channel ID, your API key, and your email.

curl -X POST 'https://api.bird.com/workspaces/<your workspace ID>/channels/<your channel ID>/messages' \
-H 'Authorization: AccessKey <your access key>' \
-H 'Content-Type: application/json' \
-d '{
  "receiver": {
    "contacts": [
      {
        "identifierValue": "<your email>"
      }
    ]
  },
  "body": {
    "type": "html",
    "html": {
      "metadata": {
        "subject": "Hello!"
      },
      "html": "<p>Congratulations, you just sent an email with Bird!</p>",
      "text": "Congratulations, you just sent an email with Bird!"
    }
  }
}'

{
  "id": "b0b858d3-75d7-4fe3-a5a3-8d7c8ee8471c",
  "channelId": "7b0eb8a0-606b-59f1-bd90-43cacb048146",
  "sender": {
    "connector": {
      "id": "fdd994a8-31fd-4b24-9c9c-0392f91aaf76",
      "identifierValue": "[email protected]"
    }
  },
  "receiver": {
    "contacts": [
      {
        "id": "18220490-9ef7-4a5a-9b9f-7db6903009d2",
        "identifierKey": "emailaddress",
        "identifierValue": "[email protected]",
        "platformAddress": "[email protected]"
      }
    ]
  },
  "body": {
    "type": "html",
    "html": {
      "text": "Congratulations, you just sent an email with Bird!",
      "html": "<p>Congratulations, you just sent an email with Bird!</p>",
      "metadata": {
        "subject": "Hello!"
      }
    }
  },
  "meta": {
    "email": {
      "subject": "Hello!"
    }
  },
  "reference": "",
  "parts": [],
  "status": "accepted",
  "reason": "",
  "direction": "outgoing",
  "context": {},
  "lastStatusAt": "2024-12-04T15:57:22.391Z",
  "createdAt": "2024-12-04T15:57:22.391Z",
  "updatedAt": "2024-12-04T15:57:22.391Z",
  "notification": {},
  "batchId": null
}

Step 5: Checking messages

You can verify the message status in the following ways:

1. UI

In the developer console, you can access Email -> Emails Log.

Alternatively, you can navigate to your channel and switch to the Logs tab.

2. API

To retrieve message details through the API, refer to the Messaging API Documentation. You can find more information on the available endpoints, request formats, and required parameters.

3. Webhook

In the Developer console, head to Preferences -> Webhooks and create a webhook subscription to the channels service with the event email.outbound. For additional information, refer to the Notifications API.

Troubleshooting

Unable to verify DNS records

If your DNS records can't be verified, use the dig tool to check that domains are responding with the expected value, for example:

$ dig scph1023._domainkey.bird.com txt +short @1.1.1.1
"v=DKIM1; k=rsa; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDM2lbd61qfnFm+EfN6nIRJYaDsBC25HF0tTw7im7qdCQ78CMRvVd9/dPmf6kPFkOQ7AHnji0uN26tpmeZ7e0B5ruPmomRAZhPMAo5okLM2ZyGfopy5JOIqwvE20NBC9S8PPIdp2Av5PvYy92ga+DY1HfWEyB6T2wbXuFyOKnuX/QIDAQAB"

Keep in mind it may take a few minutes for new DNS values to be propagated.

Another possibility is that your tracking domain is in use by another organization. To check if that's the case, make sure the health check for "Tracking Domain Exists" is OK.