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

All Email Resubscription API requests will be authenticated through Basic Authentication. Do the following to generate the Basic Authentication header:

  1. Navigate to Settings > APIs > DATA API Settings
  2. Copy the DATA API ID and DATA API KEY
  3. The basic authentication header is a 'username:password' base64 encoded string with the string 'Basic' prepended to it. Generate the Authentication string as described below:
    • Add a colon after the user name (DATA API ID) and concatenate it with the password (DATA API KEY).
    • Encode the concatenated string using base64 encoding.
    • Pass the encoded string in the HTTP authorization header as follows: {"Authorization":" Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

Request Headers

Key Mandatory/Optional Sample Values Description

MOE-APPKEY

Mandatory

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

This is the APP ID of your MoEngage account. The MOE-APPKEY has to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication.

Note: You can also fetch the APP ID from the following navigation: Settings -> App -> General Settings.

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 is the authentication parameter for access control and needs to be passed along with the request. The APP KEY and API SECRET need to be picked up from the DATA API Settings in MoEngage Dashboard, and a Basic Authorization header needs to be created and set in the header. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, 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.

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.
Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?