Custom Email Provider Integration

Bloomreach Engagement has a native integration with MailGun which can also be used for custom integrations. If you wish to use another mail provider with Bloomreach Engagement, you can create a custom integration via our Mailgun integration.

This integration consists of two steps:

  • Setting up your API
  • Bloomreach Engagement Integration Set-Up

API Set-Up

Your API needs to be set up such that it mimics MailGun’s API.

Exponea’s API call is based on the Mailgun Sending API v3, see here .
Exponea uses the first method of sending messages, we do not send MIME strings.

How it's done

1. Authentication

Authentication is accomplished using HTTP Basic Auth. The username must be set to api. The password is an API key that you can provide and add to Exponea when setting up the integration (see below).

2. Saving the integration

When saving the integration in Exponea (see below), Exponea will make a verification call to make sure that the entered domain name and API keys are set up in your system. Exponea will send a GET request to the following URL with HTTP Basic Auth:
<your-custom-url>/domains/<your-domain> .

If we receive a 200 response code in the response the integration is successfully configured and saved.

3. Sending emails

When sending emails, Exponea will send a POST request to the following URL with HTTP Basic Auth:
<your-custom-url>/<your-domain>/messages

The request payload must be url decoded, since we use a x-www-form-urlencoded header.

h:sender=John Smith<[email protected]>
from=John S,mith <[email protected]>
text=Your content here
o:tracking=yes
[email protected]
html=<html><head><meta charset="utf-8"></head><body><img alt="" height="1px" src="https://cdn.campaigns.example.com" width="1px"><p>Your content here</p></body></html>
o:tracking-clicks=no
o:dkim=yes
v:my-custom-data={
	"company_id": "be52dc2b-88d2-11e8-9f20-0a580b20261c", 
	"customer_id": "5xb1bff01677d007809eb543",
	"email_hash":	"cba3c25c07916ec4c684b98740894d00d29c1535cd42c4ebbc55cc1b685c7h5g3",
	"properties": { 
          "action_id": 3, 
          "action_name": "Request example", 
          "action_type": "email", 
          "campaign_id": "5d838d132670150010b58a16", 
          "campaign_name": "Request example", 
          "campaign_policy": "Unlimited", 
          "language": "", 
          "sent_timestamp": 1572014375.840392,
          "subject": "Test"
					}, 
	"ts": 1572014376
}
subject=Test

4. Response

The response from your API must replicate the Mailgun response message in order for Exponea to evaluate the request as successful. We check for the presence of the message and id parameter along with 200 response code.

{
	"message": "Queued. Thank you.",
	"id": "<customer/message identificator>" // id must be present but can be empty
}

Example from Mailgun here

Exponea will try to resend the request for all 5xx response codes from your API.

5. Tracking

If you use Exponea’s native email builders, open and click will be automatically tracked since Exponea generates tracking pixels in the emails and automatically rewrites links.

Tracking delivery statuses (such as delivered or hard_bounced) needs to be handled separately, by tracking the event via Exponea’s Tracking API or by importing the events via CSV.

To make Exponea’s auto-evaluation dashboards work, you need to replicate Exponea’s native campaign event structure. You should use the data from my-custom-data field to populate campaign events. Read the Campaign event doc here

For tracking delivery events from Mailgun, we use their webhooks that are tracked to Exponea automatically and translated into appropriate bounce categories as described in our Bounce management for Mailgun article. Custom email integrations can also use our Mailgun webhook endpoint for tracking campaign events. Please contact your CSM for more details.


After you have set up your API to mimic Mailgun, you need to finish the integration in Bloomreach Engagement.

Exponea Integration Set-Up

  1. In Exponea, go to Data and Assets > Integrations > Add new integration and select Mailgun.

  2. Enter your Domain name and Secret API key (password for Basic Auth).

  3. In the Region settings, chose Custom and enter your custom API URL.

600

You can read more about integrating MailGun here.

  1. Uncheck the option Handle webhooks automatically

  2. Go to Project Settings > Channels > Email and set your Mailgun integration as the default.

  3. Start sending.