Email Service Provider

Adding your ESP to WebEngage enables you to extend your services to over 40,000 global users and makes it easier for your existing clients to start using your services through their WebEngage dashboard.

How to Initiate ESP Integration

We'd love to add you to our Service Partner Network! Please feel free to initiate a conversation by dropping an email at [email protected] with the following details:

1. Service provider's test credentials.

2. A logo of the service provider with a minimum width of 370 px in PNG/JPEG format.

3. A static endpoint which listens to incoming HTTPS POST requests and adheres to the specified schema for sending email.

   • Please note that this needs to be a single static endpoint. If you have multiple such endpoints based on, for example, geography, you will have to accept WebEngage requests on a single endpoint and then route them accordingly.

4. The request authentication method (Basic authentication or Bearer authentication).

5. Input fields to be shown to the client on WebEngage dashboard. For example: API Key or Username and Password.

   • In case of API Key, the POST request will contain the header Authorization: Bearer API_KEY.
   • In case of Username and Password, the POST request will contain the header Authorization: Basic BASE_64(USERNAME:PASSWORD).
     • For example, if your username is 'webengage' and password is 'admin' then the Authorization header will be Basic d2ViZW5nYWdlOmFkbWlu. The string d2ViZW5nYWdlOmFkbWlu is the Base64 encoded version of the string webengage:admin.

Configuring Delivery Status Notifications

WebEngage provides endpoint security token for Delivery Status Notifications (DSN) that makes it easier for our clients to track their campaign's performance in their WebEngage dashboard.

What are Delivery Status Notifications?

Delivery Status Notifications are asynchronous updates to messages (for example, Email Delivered, Bounced etc.) that the service provider sends to WebEngage. This is shown in the flowchart below.

WebEngage Support will process the request if there is a mutual client willing to try out the integration and add the service provider in private beta mode on WebEngage dashboard.

1. The service provider is required to POST Delivery Status Notifications (DSNs) i.e. Email Delivered, Bounced etc. on the static endpoint https://et.webengage.com/tracking/events

2. The service provider will be provided with a security token which needs to be included as a Authorization header in the POST request of DSNs.

   • For example: Authorization: Bearer <Security Token>. This token will remain the same and should not be shared to ensure security. In case there is a need to change the token, the service provider should reach out to WebEngage Support to get a new token.

3. Please follow the below format for the POST body for DSN:

{
    "messageId": "webengage-message-id",
    "event": "DELIVERED",
    "timestamp": "2018-01-25T10:24:16+0000",
    "email": "email-id",
    "hashedEmail": "hashed-email-id",
    "statusCode": 1000,,
    "message": "Success",
    "version": "1.0"
}

WebEngage will respond to the Delivery Status Notification with an HTTP 2XX response code and will enqueue the event to process it.

🚧

Skip to: List of DNS Status Codes

Testing Integration

You can test your integration using Postman. Here's how you can configure the Postman Test Environment:

Step 1: Click the button below to import a collection of APIs which will help you test several use-cases.

Step 2: Configure the Postman environment with your account data.

Environments are a group of variables & values, that allow you to quickly switch the context for your requests and collections. Here's how you can go about it:

• Step 1: Click on the settings button next to the environment selector dropdown on the top right.

• Step 2: Select WebEngage Email ESP Test Environment. In doing so, you will see the following keys. Edit their values as per your test environment.

  a. to-email: Email ID on which you want to receive test emails.
  b. from-email: Email ID from which you want to send test emails.
  c. api-end-point: API endpoint of your integration
  d. username: Username of your Basic Auth. Leave the value as it is if you're using Bearer Auth.
  e. password: Password of your Basic Auth. Leave the value as it is if you're using Bearer Auth.
  f. api-key: API key (token) for Bearer Auth. Leave the value as it is if you're using Basic Auth.
  g. authorization: Leave as it is.
  h. message-id: Leave as it is.

Step 3: Once you have set up the environment, you are ready to test your integration. Here's how you can go about it:

• Step 1: Open Postman Collection Runner by clicking on Runner button on the top of Postman window.

• Step 2: Select the Collection with the name WebEngage Email ESP Test Suite and Environment with the name WebEngage Email ESP Test Environment.

• _Step 3:_Click the Run button. Postman will then start testing your APIs and will show you the report.

On completion of the above steps, the service provider will continue to function in private beta mode for mutual clients and will be later made public after ensuring the QoS and functionality tests.

Request

The service provider should accept the following payload as a part of the request to send Email.
The Content-Type header will always be application/json.

{
    "email": {
        "from": "[email protected]",
        "fromName": "John Doe",
        "replyTo": [
            "[email protected]",
            "[email protected]"
        ],
        "subject": "email subject",
        "text": "text body",
        "html": "html body",
        "recipients": {
            "to": [{
                "name": "Recipient1",
                "email": "abc12345"
            }, {
                "name": "Recipient2",
                "email": "[email protected]"
            }],
            "cc": [
                "[email protected]",
                "[email protected]"
            ],
            "bcc": [
                "[email protected]",
                "[email protected]"
            ]
        },
        "attachments": [{
            "name": "Attachment1",
            "url": "https://link/to/attachment/1"
        },{
            "name": "Attachment2",
            "url": "http://link/to/attachment/2"
        }]
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id",
      	"custom" : {
          	"key1" : "val1",
            "key2" : "val2"
        }
    },
    "version": "1.0"
}

{
    "email":
    {
        "from": "[email protected]",
        "fromName": "John Doe",
        "replyTo":
        [
            "[email protected]",
            "[email protected]"
        ],
        "subject": "email subject",
        "amp_html": "amp html body",
        "html": "fallback html body",
        "recipients":
        {
            "to":
            [
                {
                    "name": "Recipient1",
                    "email": "abc12345"
                },
                {
                    "name": "Recipient2",
                    "email": "[email protected]"
                }
            ],
            "cc":
            [
                "[email protected]",
                "[email protected]"
            ],
            "bcc":
            [
                "[email protected]",
                "[email protected]"
            ]
        },
        "attachments":
        [
            {
                "name": "Attachment1",
                "url": "https://link/to/attachment/1"
            },
            {
                "name": "Attachment2",
                "url": "http://link/to/attachment/2"
            }
        ]
    },
    "metadata":
    {
        "campaignType": "PROMOTIONAL",
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id",
        "custom":
        {
            "key1": "val1",
            "key2": "val2"
        }
    },
    "version": "2.0"
}

🚧

About Link Wrapping

If you are performing additional link wrapping on the links already wrapped by WebEngage (original URL) anywhere in the request payload, the wrapped domain must ask the caller to follow the original URL-encoded location.

For example, let's assume that the email body has the following hyperlink:

<a href=“https://google.co.in/?param=%3D%3D%2B%20%20abcd”> Link </a>
We have a parameter named param with a value of ==+ abcd here.

If you are further wrapping this link, then the wrapped domain must ask the caller to follow the URL-encoded location (https://google.co.in/?param=%3D%3D%2B%20%20abcd), not the decoded one (https://google.co.in/?param===+ abcd).

Response

The service provider must synchronously respond with the appropriate statusCode. Also, the message status must be included, whether it is SUCCESS or ERROR. Refer to the examples below. If there is an asynchronous update to the message later (Email Delivered, Bounced, Rejected etc.), that should be sent as a Delivery Status Notification.

🚧

Skip to: List of Response Status Codes

Example 1: Message sent successfully

HTTP 200 OK
{
    "status": "SUCCESS",
    "statusCode": 1000,
    "message": "NA"
}

Example 2: Message cannot be sent

HTTP 200 OK
{
    "status": "ERROR",
    "statusCode": 9002,
    "message": "Daily email sending quota is over."
}

Example 3: Payload not acceptable

HTTP 400 BAD REQUEST
{
    "status": "ERROR",
    "statusCode": 9022,
    "message": "Unsupported version",
    "supportedVersion": "2.0" // Mandatory in case of status code 9022
}

Status Codes

These status codes are to be used both for synchronous responses and Delivery Status Notifications. Please ensure that the HTTP status and status codes are mapped correctly at your end to avoid any confusion.

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!