Custom Mail Provider Integration

Exponea is integrated with MailGun by default. If you wish to use another mail provider with Exponea, you will need to do a custom integration.

This integration consists of two steps:

  • Setting up your API
  • Integrating with Exponea

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 generate and add to Exponea when setting up the integration (see below).

2. Payload

The request payload must be url decoded, since there is an 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

3. Response

The response from your API must replicate the Mailgun success message in order for Exponea to evaluate the request as successful.

{
	"message": "Queued. Thank you.",
  "id": "<customer/message identificator>" // id parameter 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.

4. 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 status (such as delivered or bounced) needs to be handled separately, by tracking the event via Exponea’s 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 events back from Mailgun, we currently use the older version of webhooks (deprecated).
Documentation here.

Early Q1 2020 we plan to upgrade the supported API to the newest version. Documentation here.
Once changed, we will no longer support the older version, due to different behavior and non-deterministic mapping of different states (primarily bounced and dropped).

Not to be tracked: open, click, unsubscribe
To be tracked: everything else


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

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.

You can read more about integrating MailGun here.

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

  2. Start sending.

Updated 2 months ago

Custom Mail Provider Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.