Close mobile menu

API Reference

OverviewSMSVoice CallingVoice MessagingConversationsNumbersPartner AccountsVerifyMMSHLRReportingBalanceLookupContactsGroups

Programmable Email Early Access

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

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

AttributeTypeDescription
errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameterstringThe 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.

CodeDescriptionParam
10name is required and can't be emptyname
10domainName is required and can't be emptydomainName
10domainName must be a valid domain namedomainName
10webhook is longer than 1024 byteswebhook
10channel already exists
10domain is already registered to a channel
20channel not found
21channel is not active: domain is not yet verified
21the from domain must match the registered domain for your channel
21recipient is invalid
2you 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

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the channel.
namestringThis is the name you want to give to your channel.
domainNamestringThis 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.
dkimDKIMThe Domain Key Identified Mail is a security feature to avoid email spoofing.
statusstringThe status indicates the current state of your channel, it can be one of the following: action_required, pending, running, invalid
createdDatetimedateRFC3339 formatted timestamp of the creation time of the channel.
updatedDatetimedateRFC3339 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.

AttributesTypeDescription
publicstringThe public portion of the DKIM signature.
selectorstringThe selector for the TXT record, it should have the the shape: scph0319._domainkey.*
signingDomainstringThis is your domain, as used to create the secure signature.
recordstringA representation of the TXT record that needs to be added to your DNS settings.
headersstringHeaders 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

Register a new channel for a given domain.

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.

Content for Messages can be sent with parts for HTML, plain text, or both.

AttributesTypeDescription
idstringA unique random ID for this message on the MessageBird platform, returned upon acceptance of the message.
toArray of RecipientRequired. An array containing of all the recipients of the message.
fromRecipientRequired. 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.
subjectstringRequired. This will be displayed as the subject in the message, expected in the UTF-8 charset without RFC2047 encoding.
contentContentRequired. HTML or text content for the email. At least one type of content is required.
replyTostringEmail address used to compose the email’s “Reply-To” header.
returnPathstringEmail address used to compose the email’s “Return-Path” header. Must match your sending domain.
headersobjectObject containing custom headers other than Subject, From, To, and Reply-To. These will be sent along with your message.
trackingTrackingOptional. Allows you to set tracking options.
reportUrlstringThe URL for delivery of status reports for the message. Must use https.

Content

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

AttributesTypeDescription
htmlstringHTML content of the message, expected in UTF-8.
textstringPlain 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.

AttributesTypeDescriptionExample
emailstringRequired. Valid email addressdemo@messagebird.com
namestringName attached to the email address, this appears in the To field in a users email clientJane Doe
variablesobjectList of variables used for placeholders inside the content or headers of your email

Tracking

AttributesTypeDescription
openboolAdds a tracking pixel to handle message.opened events. (Default: true)
clickboolAdds link-wrapping to handle link.clicked events. (Default: true)

Example Message

{
"id": "884740337d0d4ceb97883e8adf5d7b71",
"to": [
{
"name": "John Doe",
"address": "john.doe@example.org",
"variables": {
"firstname": "John",
"orderNo": "ABC-321"
}
},
],
"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.

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. <b>Best from Amsterdam</b>"
},
"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",
}

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.

CodeType
10Bounced email
11Email 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": "",
"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>"
},
"createdDatetime": "2019-05-15T15:47:23Z"
}
},
"timestamp": "2019-05-08T13:19:06.019325+02:00"
}
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