API Reference

MessageBird's Programmable Email API enables you to send and receive emails using your own domain. You can use the API to do this programmatically or you can choose to integrate the API with your own frontend solution, such as a CRM.

To enable two-way email communication, you'll need to first create a MessageBird email channel, through which you can register your domain. Once set up, you'll be able to both send transactional emails to one or many recipients with a single API call, as well as also receive emails.

As a prerequisite, you will need access to the DNS configuration of the domain you want to send email from during the setup of an email channel.

API Endpoint

https://email.messagebird.com/v1

Endpoints Summary

POST /v1/channels
GET /v1/channels
GET /v1/channels/{id}
PATCH /v1/channels/{id}
DELETE /v1/channels/{id}
POST /v1/send

Data Retention

The emails which are directly sent through Email Service, will be removed after 30 days.

Authorization

With each API call you'll need to set an access key to authenticate yourself. API keys can be created or retrieved through the MessageBird Dashboard.

To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.

Formats and Headers

All API responses are in JSON. You're required to send the Accept header with the value application/json with each request.

POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).

In the case of an error, the body of the response includes a JSON-formatted response that tells you exactly what is wrong.

Error Object Example

{
  "errors": [
    {
      "code": 1001,
      "description": "You are requesting with an invalid credential.",
      "parameter": null
    }
  ]
}

Attributes

Attribute	Type	Description
errors[].code	integer	An integer that represents the error type.
errors[].description	string	A human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameter	string	The parameter in your request related to the error if the error is parameter specific.

Possible errors

The following table documents errors that could be returned with an HTTP Status in the 4XX range indicating the request was not accepted.

Code	Description	Param
10	name is required and can't be empty	name
10	domainName is required and can't be empty	domainName
10	domainName must be a valid domain name	domainName
10	webhook is longer than 1024 bytes	webhook
10	channel already exists
10	domain is already registered to a channel
20	channel not found
21	channel is not active: domain is not yet verified
21	the from domain must match the registered domain for your channel
21	recipient is invalid
2	you have reached the API rate limit, please try again later

The Channel object

A Channel represents a registered domain used for sending email from you to your customers. The domain that you configure for a channel allows emails to be sent from <your email>@<your domain> in the From: header of an email sent to your customers.

Attributes

Attribute	Type	Description
id	string	A unique random ID which is created on the MessageBird platform and is returned upon creation of the channel.
name	string	This is the name you want to give to your channel.
domainName	string	This is the domain you are going to use to send your emails, to be able to sent emails using your domain, you have to have access to the DNS configuration.
dkim	DKIM	The Domain Key Identified Mail is a security feature to avoid email spoofing.
status	string	The status indicates the current state of your channel, it can be one of the following: action_required, pending, running, invalid
createdDatetime	date	RFC3339 formatted timestamp of the creation time of the channel.
updatedDatetime	date	RFC3339 formatted timestamp of the time of the last update made to the channel.

Example Channel

{
        "id":"0fc77eed542d4397b8eac6725b626472",
        "name":"My Domain",
        "domainName":"mail.mydomain.nl",
        "dkim":{
                "public":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDTu/keSOLIZfDAcccfqwXg9QSLrwNfyqGxt9nsdO60ZQjr0k3/li1CaPgOowAtLg1b4jbhPeIED3/TzxJN7o6kD7zR/eintEQPskPsb89TCeXAzkfOebTE6AWacEqI4IPHljGXhj3NMStMvfrtdbV4o8to5EWrIB5YcyyZE52QxQIDAQAB",
                "selector":"scph0319._domainkey.mail.mydomain.nl",
                "headers":"from:to:subject:date",
                "signingDomain":"mail.mydomain.nl",
                "record":"k=rsa; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDTu/keSOLIZfDAcccfqwXg9QSLrwNfyqGxt9nsdO60ZQjr0k3/li1CaPgOowAtLg1b4jbhPeIED3/TzxJN7o6kD7zR/eintEQPskPsb89TCeXAzkfOebTE6AWacEqI4IPHljGXhj3NMStMvfrtdbV4o8to5EWrIB5YcyyZE52QxQIDAQAB"
        },
        "status":"action_required",
        "createdDatetime":"2019-03-29T15:47:02Z",
        "updatedDatetime":"2019-04-02T14:01:34Z"
},

DKIM

The DKIM record includes the TXT record you need to add to your DNS settings to enable DKIM verification once an email reaches the mail client of your customer, and some additional information about the public key and headers used for signing.

Attributes	Type	Description
public	string	The public portion of the DKIM signature.
selector	string	The selector for the TXT record, it should have the the shape: scph0319._domainkey.*
signingDomain	string	This is your domain, as used to create the secure signature.
record	string	A representation of the TXT record that needs to be added to your DNS settings.
headers	string	Headers used to create the secure signature.

DKIM and DMARC Verification

We currently support sending emails with DKIM (DomainKeys Identified Mail) and DMARC (Domain Message Authentication Reporting & Conformance) verification.

DKIM is an authorization mechanism that detects forged sender addresses in emails. DKIM works by allowing a receiving mail client to validate that a specific piece of mail that appears to come from a domain was authorized (by way of digital signature) by the person with ownership of that domain.

When you create a new channel we will provide you a DKIM record that must be inserted into the DNS configuration for your domain, typically via your DNS provider. Once you've added your DKIM record to your DNS, the channel will automatically verify the DKIM record and become ready for use after a period of up to 10 minutes. MessageBird will verify the status of your DNS records regularly to ensure the DKIM is configured correctly and keep the status of the channel up-to-date to reflect this.

DMARC is an extension mechanism that leverages DKIM to provide an additional guarantee that the displayed sender address (also known as the "From address") of an email is in alignment with the domain used for DKIM verification. With DKIM alignment, the d= tag in the DKIM-Signature header must be aligned with the domain used in the From: header of the mail, i.e. the displayed from address. Alignment in this case can be "strict", where the domains must be identical, or "relaxed", where the organisational domain must match and a subdomain can be used.

To be able to validate your messages using DMARC, you need to access your DNS configurations and add a new TXT record with your DMARC configuration. An example DMARC record looks like:

v=DMARC1; p=none; pct=100; rua=mailto:agg@myexmapledomain.com; ruf=mailto:for@myexampledomain.com;

Where "p" is the policy you want to adopt when a message fails the DMARC validation, "pct" is the percentage of mail to which you would like to have the DMARC policy applied to and "rua" and "ruf" are the receivers of the reports created when the messages are validated. If you want to access these reports, set these fields to a valid email address within your domain. To see more information on how to create your DMARC record and all the policy options, go to: https://tools.ietf.org/html/rfc7489#section-6.1.

Create a Channel

Definition

POST https://email.messagebird.com/v1/channels

Example request

curl -X POST https://email.messagebird.com/v1/channels
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy'
  -H 'Content-Type:application/json'
  -d '{
    "name": "My Domain",
    "domainName": "mydomain.nl"
  }'

Response

A Channel object as described above.

Example response

{
    "id":"62722892655145ef8f6a9583ba4b2a05",
    "name":"My Domain",
    "domainName":"mydomain.nl",
    "dkim":{
            "public":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDO8iO0m1cE1TSnrIkkYh2qUBgUj/nKtBs1pz/XSlvx3w2w+v1f0ZF657FISXVW8xqaDRrT49O/JRw+tkz7AY92G4zLySup5gEV9c9R3q/U1sewQ9slEyAkPlMz2Prw/w29zGD4PZPGcNc6qZIlnbHTrWQnm+Pm+7Lh8g5Qh3abpQIDAQAB",
            "selector":"scph0319._domainkey.mail.mydomain.nl",
            "headers":"from:to:subject:date",
            "signingDomain":"mydomain.nl",
            "record":"k=rsa; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDO8iO0m1cE1TSnrIkkYh2qUBgUj/nKtBs1pz/XSlvx3w2w+v1f0ZF657FISXVW8xqaDRrT49O/JRw+tkz7AY92G4zLySup5gEV9c9R3q/U1sewQ9slEyAkPlMz2Prw/w29zGD4PZPGcNc6qZIlnbHTrWQnm+Pm+7Lh8g5Qh3abpQIDAQAB"
    },
    "status":"action_required",
    "createdDatetime":"2019-04-05T13:34:49Z",
    "updatedDatetime":"2019-04-05T13:34:49Z"
}

The Message Object

A Message is an Email that can be sent via the API to one or more recipients. A message can be thought of as a single message to an end-user, such as a password reset form, or a campaign message sent out with a pre-defined template to many users at once.

E-mail message content can be set as HTML, plain text or both. Attachments and inline images need to be uploaded before posting the request to send the message. For more details about how to upload attachments and inline images, refer to the Uploading attachments and inline images section.

Attributes	Type	Description
id	string	A unique random ID for this message on the MessageBird platform, returned upon acceptance of the message.
to	Array of Recipient	Required. An array containing of all the recipients of the message.
cc	Array of Recipient	Optional. An array containing of all the recipients who will be in the cc field of the email.
from	Recipient	Required. Name / address that will be displayed in the from field of the sent messages, the domain in the address email must be registered to one of your channels.
subject	string	Required. This will be displayed as the subject in the message, expected in the UTF-8 charset without RFC2047 encoding.
content	Content	Required. HTML or text content for the email. At least one type of content is required.
replyTo	string	Email address used to compose the email’s “Reply-To” header.
returnPath	string	Email address used to compose the email’s “Return-Path” header. Must match your sending domain.
headers	object	Object containing custom headers other than Subject, From, To, and Reply-To. These will be sent along with your message.
tracking	Tracking	Optional. Allows you to set tracking options.
reportUrl	string	The URL for delivery of status reports for the message. Must use https.
attachments	array of Attachment	Optional. List of files attached to a message.
inlineImages	array of InlineImage	Optional. List of inline images added to the message content.
mode	string	Optional. If it's set to campaign, destinations won't see each other in the email message. If it's set to normal, destinations will see each other in the email message.

Content

The Content object represents the content to be included as the body of your message, it can contain either HTML or plain text.

Attributes	Type	Description
html	string	HTML content of the message, expected in UTF-8.
text	string	Plain text of the message, expected in UTF-8.

Recipient

You can specify the recipients of your email as an array of objects with the properties listed below. Variables added for each recipient are used to customise the content sent to a user if a template with matching dynamic placeholders is used in the body or custom headers. Additional variables not present in the content or headers are ignored.

Attributes	Type	Description	Example
address	string	Required. Valid email address.	demo@messagebird.com
name	string	Name attached to the email address, this appears in the To field in a users email client.	Jane Doe
variables	object	List of variables used for placeholders inside the content or headers of your email.

Tracking

Attributes	Type	Description
open	bool	Adds a tracking pixel to handle message.opened events. (Default: true)
click	bool	Adds link-wrapping to handle link.clicked events. (Default: true)

Attachment

The Attachment object represents a file attached to a particular message. The maximum attachment size is 20 MB.

Attributes	Type	Description
id	string	Attachment ID.
name	string	File name.
type	string	File type.
URL	string	URL of the file to be attached to the message.
length	integer	File size in bytes.

Inline images

The Inline Image object represents a image added to the message content. The maximum image size is 20 MB.

In order to use the inline image in the content of the message, you must refer the contentId using the img tag. For example: <img src="cid:<contentId>">

Attributes	Type	Description
id	string	Inline image ID.
name	string	File name.
type	string	File type.
URL	string	URL of the file.
length	integer	File size in bytes.
contentId	string	ID used in the content of the message.

Example Message

{
  "id": "884740337d0d4ceb97883e8adf5d7b71",
  "to": [
        {
      "name": "John Doe",
      "address": "john.doe@example.org",
      "variables": {
        "firstname": "John",
        "orderNo": "ABC-321"
      }
    },
  ],
  "cc": [
        {
      "name": "Michael Doe",
      "address": "michael.doe@example.org",
    },
  ],
  "from": {
    "name": "MessageBird",
    "address": "noreply@email.customer.com"
  },
  "content": {
            "html":"<b>Hello {{firstname}}!</b><br><br>Your order <b>{{orderNo}}</b> has been accepted.",
            "text":"Hello {{firstName}}! Your order {{orderNo}} has been accepted."
    },
  "replyTo": "support@customer.com",
  "headers": {
    "X-MessageBird-Greeting": "Hello {{firstname}}!"
  },
  "createdDatetime": "2019-03-26T12:20:48Z",
  "reportUrl": "http://customer.com/webhooks/inbound-email"
}

Send a Message

Send a new message to one or many recipients.

You won't be able to send any messages until the domain for your channel is verified after adding the DKIM record to your DNS. Keep in mind that DNS changes may take some time to propagate.

Before sending a message with attachments or inline images, you need to upload your files/images to the Messaging API and then use IDs in the payload. For more information about how to upload attachments, refer to the Uploading attachments and inline images section.

The entire message content, including all attachments, inline images, text and html, should not exceed 20 MB, otherwise they will be rejected.

Definition

POST https://email.messagebird.com/v1/send

Example: Send an HTML message to a single recipient

curl -X POST https://email.messagebird.com/v1/send
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
  -H 'Content-Type:application/json'
  -d '{
  "subject":"A great message!",
  "to":[
    {
      "name": "Customer",
      "address": "one@happycustomer.com"
    }
   ],
   "from": {
     "name": "You",
     "address": "email@yourdomain.com"
   },
   "content":{
     "html": "Hello! This is a test message. <img src="cid:my-inline-image"> <b>Best from Amsterdam</b>"
   },
   "inlineImages": [
    {
      "ID": "6505d283-7a8d-493c-9ea0-6d38c6bd495a"
      "contentId": "my-inline-image"
    }
   ],
   "attachments": [
     {
        "ID": "ebf6acee-d7ae-4375-b726-e247318d3377"
     }
   ],
   "reportUrl":"http://mywebhooksreceiver.com/"
  }'

Send a templated message

It's possible to add placeholder variables to your email. You can insert these using double curly braces. The value of each placeholder key needs to be set on a per recipient basis in their variables array.

All variables will be escaped by default. However, if you would like to keep raw encoding for URLs or inline HTML for example, you can use triple curly braces.

Example: Send a templated message to multiple recipients

curl -X POST https://email.messagebird.com/v1/send
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
  -H 'Content-Type:application/json'
  -d '{
  "subject":"A great message!",
  "to":[
    {
      "name": "Customer 1",
      "address": "one@happycustomer.com",
      "variables": {
        "location": "Amsterdam",
        "visit_us": "https://yourdomain.com/landingpage?utm_source=email"
      }
    },
    {
      "name": "Customer 2",
      "address": "two@happycustomer.com",
      "variables": {
        "location": "San Francisco",
        "visit_us": "https://yourdomain.com/landingpage?utm_source=email"
      }
    },
   ],
   "from": {
     "name": "You",
     "address": "email@yourdomain.com"
   },
   "content":{
     "html": "Hello! This is a test message. <b>Best from {{location}}!</b><br><a href="{{{visit_us}}}">Visit us!</a>",
     "text": "Hello! This is a test message. Best from {{location}}! Visit us: {{{visit_us}}}"
   },
   "reportUrl":"http://mywebhooksreceiver.com/"
  }'

Response

A object with an ID for the message, which you can use to track webhook events generated by the delivery of this message.

Example response

{
  "id": "ff142bd7a8f34db6badae439740022b6",
}

Upload attachments and inline images

Before sending an email with attachments or inline images, they need to be uploaded to the Messaging API. It is mandatory to provide the Content-Type in the HTTP headers, and also chucked transmission is not supported yet.

Definition

POST https://messaging.messagebird.com/v1/files

Example: Uploading a file to Messaging API

curl -X POST https://messaging.messagebird.com/v1/files
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
  -H 'Content-Disposition: attachment; filename="testing_image.png"'
  -H 'Content-Type: image/png'
  --data-binary @input_image.png

Response

Returns an object with an ID, which you can use while sending an email with attachments or inline image.

Example response

{
  "id": "ebf6acee-d7ae-4375-b726-e247318d3377",
}

Fetching files

You need to provide the ID for fetching the attachment/inline image. The ID has given you when you uploaded the attachment/inline image.

Definition

GET https://messaging.messagebird.com/v1/files/<file-id>

Example: Fetches the file from Messaging API

curl -X GET https://messaging.messagebird.com/v1/files/ebf6acee-d7ae-4375-b726-e247318d3377
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
  --output uploaded_image.png

Receiving status updates for sent Messages

You can request that message delivery events be sent to your server through Webhooks. When sending a message, the optional reportUrl attribute can be used to provide the url of where you want us to deliver webhook notifications for events generated by that message. The message ID that you were returned on sending will be included for all events generated by that message. If the report url is provided, you will receive POST requests with JSON content of events for:

Delivery statuses: accepted, sent, opened, or failed, per each individual recipient in the message.
Link tracking: triggered whenever a link is clicked in your email by an individual recipient.

When dealing with failed messages you can use the code in the error object to programmatically check what kind of failure occurred and the description will give more detail if available.

Code	Type
10	Bounced email
11	Email marked as spam

Emails being sent to multiple recipients will generate webhooks for each recipient. For example, sending a message to 500 recipients would generate ~1500 events when each individual recipient email is accepted, sent, and opened.

Examples

Example webhook formats for the possible events are provided.

Example: Message Accepted

{
    "type": "message.accepted",
    "id": "299fbcc742ff4df28ed07f64564fe2f8",
    "recipient": "customer@messagebird.com",
    "timestamp": "2019-04-05T14:07:51Z"
}

Example: Message Sent

{
    "type": "message.sent",
    "id": "299fbcc742ff4df28ed07f64564fe2f8",
    "recipient": "customer@messagebird.com",
    "timestamp": "2019-04-05T14:07:51Z"
}

Example: Message Opened

{
    "type": "message.opened",
    "id": "299fbcc742ff4df28ed07f64564fe2f8",
    "recipient": "customer@messagebird.com",
    "timestamp": "2019-04-05T14:07:51Z"
}

Example: Message Failed

{
    "type": "message.failed",
    "id": "299fbcc742ff4df28ed07f64564fe2f8",
    "recipient": "customer@messagebird.com",
    "timestamp": "2019-04-05T14:07:51Z",
    "error": {
        "code": 11,
        "description": "Reported as spam"
    }
}

Example: Link Clicked

{
    "type": "link.clicked",
    "id": "299fbcc742ff4df28ed07f64564fe2f8",
    "recipient": "customer@messagebird.com",
    "timestamp": "2019-04-05T14:07:51Z",
    "link": {
        "url": "https://www.mesagebird.com"
    }
}

Receiving email

For instances where you need to receive emails, for example customer support use cases, you can configure your channel to enable inbound email.

To receive email on your MessageBird channel you need to setup a Forwarding Rule with your mail provider.

You can forward email to <channel ID>@fwd-sp.messagebird.com to have MessageBird receive a copy of inbound mail, and receive it in your application via webhooks. The original email will still exist in your mail provider.

To receive webhook notifications when an inbound email arrives, you can set an Inbound Webhook on your Channel configuration page. Make sure you set up your webhook before adding the Forwarding Rule as some providers are known to send confirmation emails to the designated inbox to test for authorization.

Received Email webhook example

{
    "type": "message.received",
    "message": {
      "id": "2fa764dd4f0f4a478c55d357c03dbf25",
      "direction": "inbound",
      "threadId": "9ee97e35970a402c8c776ab446fc17a1",
      "messageId": "<CAHGjuC7R=eTA_i9_TsDTDO4yzt+mKqfKuGMLCayxBKJrA+aMhA@messagebird.com>",
      "inReplyTo": "<ad27e9240ba241a792ce54dfd330f360-484d6b263c4d4abc8a64e29cd799c71e@messagebird.com>",
      "email": {
          "channelId": "299fbcc742ff4df28ed07f64564fe2f8",
          "id": "299fbcc742ff4df28ed07f64564fe2f8",
          "from": {
              "address": "customer@messagebird.com"
          },
          "to": [
              {
                  "name": "MessageBird Support",
                  "address": "support@messagebird.com"
              }
          ],
          "subject": "How do I receive webhook notifications?",
          "content": {
              "html": "Hi there! <img src="cid:mb_logo1">",
              "text": ""
          },
          "headers": {
              "Content-Type": "multipart/alternative; boundary=\"0000000000006535a30587bb58d3\"",
              "Date": "Tue, 30 Apr 2019 10:39:44 +0200",
              "From": "Customer <customer@messagebird.com>",
              "MIME-Version": "1.0",
              "Message-ID": "<CAHGjuC7R=eTA_i9_TsDTDO4yzt+mKqfKuGMLCayxBKJrA+aMhA@messagebird.com>",
              "Return-Path": "<support+caf_=fwd=messagebird.dev@messagebird.com>",
              "Subject": "How do I receive webhook notifications?",
              "To": "MessageBird Support <support@messagebird.com>"
          },
          "inlineImages": [
              {
                  "id": "97240ffbd206443b9c209e0cbb4cefee",
                  "name": "mg-logo.png",
                  "type": "image/png",
                  "url": "https://messaging-staging.messagebird.com/v1/files/1a3ca47e-f4a3-4d16-9f87-00a7e54464c4",
                  "length": 2797,
                  "contentId": "mb_logo1"
              }
          ],
          "attachments": [
              {
                   "id": "f7aeb180610945fd9a49182264519501",
                   "name": "messagebird.gif",
                   "type": "image/gif",
                   "url": "https://messaging-staging.messagebird.com/v1/files/62dbfe39-2db8-40f8-8037-3d9e116da984",
                   "length": 11961,
                   "messageId": "2fa764dd4f0f4a478c55d357c03dbf25"
              }
          ],
          "createdDatetime": "2019-05-15T15:47:23Z"
        }
    },
    "timestamp": "2019-05-08T13:19:06.019325+02:00"
}

Is this page useful?

Next upApi

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings