Resubscribe Email API

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

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 App 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

Key Mandatory/Optional Sample Values Description

MOE-APPKEY

Mandatory

{"MOE-APPKEY": "APP ID"}

This is the APP ID of your MoEngage account.

You can find your MoEngage APP ID in the following navigation on the Dashboard:

Revamped UI: Settings -> Account -> APIs -> App ID

Old UI: Settings -> API -> General Settings -> DATA API

Content-Type

Mandatory

{"Content-Type": "application/json"}

Set the Content-Type header to application/json for using the Resubscription API.

Authorization

Mandatory

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

Request Body

Key Mandatory/Optional Data Type Description

recipients

Mandatory

String Array

This field contains the email ids of the users who have resubscribed. For example, 

"recipients": ["john@example.com", "mike@example.com"]

Note: If an email address matches multiple profiles, all the profiles will be marked as resubscribed on the MoEngage dashboard (the unsubscribe flag will be set to false for the user).

esp

Mandatory

String

This field contains information about the Email Service Provider (esp) whose suppression list needs to be updated. For example, “esp”: “SENDGRID” would imply that the email address of the customers who have resubscribed to your brand need to be removed from SendGrid’s suppression list.

update_esp

Optional

Boolean

This field’s default value is false when it is not sent in the request payload. MoEngage calls the ESP to remove the email addresses from their email suppression list when this field is true.

request_id

Mandatory

String

This field contains the value of the identifier for the request.

Response

Key Data Type Description

message

String

This field contains a brief description of the request status.

response_id

String

This field contains the unique identifier for the response and is present in the response only when the request is successful.

error

JSON Object

This object is present in the response only in the case of an error.

"error": {

    "message": <error_message>,

    "err_code": <error_code>

}

<error_message> is a String that contains a brief description of the error for unsuccessful requests.

<error_code> is  String that contains the error code for unsuccessful requests.

If the connector settings are not valid, an error will be displayed with the message Valid email settings not present and response code 400.

Response Codes

Status Code Request State Description

202

Success

This response is returned when the request is processed successfully. 

400

Bad Request

This response is returned when the recipients field is not present in the request body.

401

Authorization Failure

This response is returned when the authorization fails when the value provided for the MOE_APPKEY header does not match the app key provided in Auth username or when the authorization fails due to the APP SECRET key not being set on the Dashboard.

405

Method not allowed

This response is returned when the HTTP method of the API is changed from POST to any other (ex.- DELETE, GET, etc).

415

Unsupported media type

This response is returned when the header Content-Type is not provided/is not supported.

429

Rate Limit Breach

This response is returned when the number of requests has exceeded the rate limit.

500

Internal Server Error

This response is returned when the system runs into an unexpected error.

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

202 400 401 405 415 429500
Sample response for a successful request
{
    "message": "The request is submitted successfully.",
    "response_id": "SrTuWVlPsq"
}

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.

Previous

Next

Was this article helpful?
1 out of 1 found this helpful

How can we improve this article?