Email Service Provider

How an Email Service Provider can integrate its platform with WebEngage

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.


Click to enlarge

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

  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"
messageIdThis is the unique ID assigned to the message which is used to identify a message uniquely.

This is received by the service provider in the request body. The length of this string can be up to 500 characters. The messageId provided in DSNs must be the same as that received from WebEngage in the request. You must not modify it.
eventThe event being reported by this DSN. This can be one of SENT, DELIVERED, BOUNCE or UNSUBSCRIBE.
timestampThe time when the event that this DSN represents happened. This follows the ISO date format: yyyy-MM-ddTHH:mm:ss±hhmm.
emailEmail ID of the user for whom this event has happened. Note that either one of email or hashedEmail is mandatory.
hashedEmailHashed email ID of the user for whom this event has happened. Note that either one of email or hashedEmail is mandatory.
statusCodeStatus code of this DSN. This must be one of the status codes described below.
messageUse this to describe the status of the DSN.
versionThis indicates the payload contract of the request. If there is any change in the payload structure in future, the version will be updated.

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.

Run in Postman

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.


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": "http://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"
versionIndicates the payload contract. If there is any change in the payload structure in future, the version will be updated.
campaignTypeThe value of this key can be either PROMOTIONAL or TRANSACTIONAL as selected by the user creating campaign on WebEngage dashboard.
messageIdUnique ID assigned to the message which should be used in further Delivery Status Notifications to identify a message uniquely.
timestampThe time when the message was triggered from the WebEngage system. This follows the ISO date format: yyyy-MM-ddTHH:mm:ss±hhmm.
metadataThis can contain additional fields. Service provider's integration should be able to ignore these additional fields passed as metadata.


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=“”> 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 (, not the decoded one ( abcd).


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

    "status": "SUCCESS",
    "statusCode": 1000,
    "message": "NA"

Example 2: Message cannot be sent

    "status": "ERROR",
    "statusCode": 9002,
    "message": "Daily email sending quota is over."

Example 3: Payload not acceptable

    "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.

Status CodeDescriptionHTTP Status
9001Throttling error.

To handle the loads with increasing customer base, WebEngage has introduced autoscaling which can occasionally result in higher call rates. WebEngage supports throttling from ESP end to handle such cases. Sending this status code will activate throttling for that request and WebEngage will send that request at later time.

1. WebEngage will retry sending the message 10 times if this status is received.
2. Time interval between retries follows binary exponential backoff: 0ms, 200ms, 400ms, 800ms...
9002Message sending quota exceeded200
9003Authentication failure403
9004Recipient address not specified400
9005From field missing400
9006Soft bounce (temporarily deferred)200
9007Hard bounce200
9008Email reported as spam200
9009Email unsubscribed200
9010Email in suppression list200
9011Sender address not verified400
9012ESP rejected message200
9013Request to ESP expired200
9014ESP unavailable500
9015IP not whitelisted with ESP401
9016Subject field empty400
9017Invalid sender address400
9018Invalid email address400
9019Recipient’s mail box is full200
9020Error processing email at Private ESP500
9021Mailbox was not found on email server200
9022Unsupported or unknown version
In this case the supportedVersion is to be sent mandatorily, i.e., the version supported by the service provider. For example:
HTTP 400 BAD REQUEST { "status": "ERROR", "statusCode": 9022, "message": "Unsupported version", "supportedVersion": "2.0" }
9024Authorization failure403
9452Message overloading200
9512Host email server not found200
9999Unknown error occurred200

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!