Overview

This API can be used to resubscribe users who have previously unsubscribed on the MoEngage platform and an external email vendor platform simultaneously. This API resets the unsubscribe flag to “false” for users on MoEngage and makes a call to an External Service Provider (ESP) like SendGrid to remove the email addresses (associated with the unsubscribed users) from their suppression list.

API Endpoint

POST https://api-0X.moengage.com/emails/v1.0/bulk-resubscribe

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

1. Navigate to Settings -> Account -> APIs.
2. Click Generate Key in the Data tile in the API Keys section, and click Save.
3. Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

1. Navigate to Settings -> APIs -> DATA API Settings.
2. Click Generate Key.
3. Click Save on the Data APIs settings section. 
4. Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

Request Headers

Request Body

Response

Response Codes

Supported ESPs

The Resubscription API supports only SendGrid.

Rate Limit

The rate limit is 10 RPM. The allowed volume is 14.4K requests per day, and the payload size is 100 recipient email addresses per request.

Sample cURL Request

curl --location --request POST 'https://api-0X.moengage.com/emails/v1.0/bulk-resubscribe' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY==' \
--data-raw '{
  "recipients": ["jane@domain.com","mike@example.com","john.doe@example.com"],
  "update_esp": true,
  "esp": "SENDGRID",
  "request_id": "636b77e6e2cf83277195fb60"
  }'

Sample Response

Sample response for a successful request
{
    "message": "The request is submitted successfully.",
    "response_id": "SrTuWVlPsq"
}

Sample response for recipients field is not present in request body
{
    "response_id": "wkskLzEMwM",
    "error": {
        "message": "Request_Body is mandatory. Kindly add request_body and the desired fields in the API payload.",
        "err_code": "BadRequest"
    }
}

Sample response for 'request_id' field is not present in request body
{
    "response_id": "jLcIFgNqiF",
    "error": {
        "message": "request_id - Field is required but value is None",
        "err_code": "InvalidFieldValue"
    }
}

Sample response for request body is not provided
{
    "response_id": "wkskLzEMwM",
    "error": {
        "message": "Request_Body is mandatory. Kindly add request_body and the desired fields in the API payload.",
        "err_code": "BadRequest"
    }
}

Sample response for invalid key in the request body
{
    "response_id": "gPrSPOPNtT",
    "error": {
        "message": "This API only supports 'Recipients', 'update_esp', 'esp' and 'request_id' as fields in the Request Body. Kindly remove other fields and try again",
        "err_code": "InvalidRequestBody "
    }
}

Sample response for more than 100 email addresses are provided in recipient array
{
    "response_id": "ofVaFGNZeU",
    "error": {
        "message": "Payload limit is set to 100",
        "err_code": "BadRequest"
    }
}

Sample response for when an integer or boolean is provided as recipient
{
    "response_id": "CNjLIXzCxP",
    "error": {
        "message": "Please provide input in a valid email address format (example@domain.com) as part of 'Recipients'.",
        "err_code": "InvalidInput"
    }
}

Sample response for empty recipients field
{
    "response_id": "VkJTiAOgxt",
    "error": {
        "message": "Add at least one email address as part of the 'Recipients'",
        "err_code": "InvalidInput"
    }
}

Sample response for incorrect values for the APP KEY/ HTTP auth header
{
    "response_id": "YNJhkZzfqt",
    "error": {
        "message": "MOE_APPKEY doesn't match the Username (APP_KEY) used in Basic Auth authorization.",
        "err_code": "HeaderMismatch"
    }
}

Sample response for when MOE-APPKEY header is not provided
{
    "response_id": "ptkMUbdHGl",
    "error": {
        "message": "MOE-APPKEY is missing in Header",
        "err_code": "HeaderMissing"
    }
}

Sample response for when username is not provided in the auth header
{
    "response_id": "RLuJLVlJap",
    "error": {
        "message": "Username (APP_KEY) is missing in the Basic Auth authorization.",
        "err_code": "AuthenticationMissing"
    }
}

Sample response for when password  is not provided in the auth header
{
    "response_id": "dKzDpSIiCG",
    "error": {
        "message": "Password (APP_SECRET) is missing in the Basic Auth authorization.",
        "err_code": "AuthenticationMissing"
    }
}

Sample response for when other authorization types are used instead of Basic Auth
{
  "response_id": "OULwnOIADe",
  "error": {
    "message": "Invalid authorization used. MoEngage only supports 'Basic Auth' authorization.",
    "err_code": "AuthenticationInvalid"
  }
}

Sample response for when API SECRET Key has not been set in the Dashboard
{
    "response_id": "YNJhkZzfqt",
    "error": {
        "message": "APP_SECRET is not set in the dashboard. Please login to the dashboard to set an API key in Settings.",
        "err_code": "AuthenticationMissing"
    }
}

Sample response for incorrect HTTP method usage
{
    "response_id": "GudkCOBkHT",
    "error": {
        "message": "This API only supports the POST method. Kindly update the method and retry again.",
        "err_code": "MethodNotAllowed"
    }
}

Sample response for unsupported media type
{
    "response_id": "quUXnIinLK",
    "error": {
        "message": "The header 'Content-Type' is missing. Kindly provide the header 'Content-Type' and set it as 'application/json'",
        "err_code": "HeaderMissing"
    }
}

Sample response for rate limit breach
{
    "response_id": "quUXnIinLK",
    "error": {
        "message": "Rate limit exceeded",
        "err_code": "TooManyRequests"
    }
}

Sample response for unknown errors
{
    "response_id": "quUXnIinLK",
    "error": {
        "message": "Please Contact Moengage Team",
        "err_code": "INTERNAL_SERVER_ERROR"
    }
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

• What happens when the update_esp field is not sent in the request?
  We will automatically call the ESP to remove the recipient email addresses sent in the request from their suppression list.
• Which attribute stores the user’s email address in MoEngage?
  This attribute is configured in the User Attribute that stores user’s email address field in the General Settings for the Email channel. You can either use the “Email Standard” attribute that MoEngage uses by default or configure any other custom attribute of your choice to store the email address of your users. This attribute is available in the User Profile for each user.
  The Resubscription API will use this attribute to look for the users mapped to the email addresses in the recipient list and update their subscription status.
• What happens when there are multiple connectors enabled for an account?
  The Current Connector field in Email -> General Settings has the information about which ESP is used. The Resubscription API will use this information to update the suppression list in the ESP.
• What happens when an ESP other than SENDGRID is mentioned in the request?
  If any other ESP is sent in the request or configured as the default connector, then only the Unsubscribe standard attribute in MoEngage will be updated to false, and the ESP will not be updated (only Sendgrid ESP is supported for the Resubscription API).
• What happens if a resubscription request is performed when the ESP is changed in the MoEngage Dashboard?
  When the ESP is changed in the Email General Settings, it takes up to 15 minutes for the settings to get reflected. If a resubscription request is executed within this time frame, the older settings will get picked. For example, if the ESP is changed from Amazon to SendGrid and a resubscription request is performed within 15 minutes of updating the settings, the ESP would still be Amazon. The unsubscribe flag will get updated in the MoEngage Dashboard alone.
• What is the difference between resubscribing using the Data API and the Resubscribe Email API?
  You can use the Data API to resubscribe a user (the unsubscribe flag will be set to false for the user in the User Profile) in MoEngage alone. However, with the Resubscribe Email API, you can resubscribe in both the ESP (SendGrid for example) and MoEngage.