openapi: 3.0.0
info:
  title: MoEngage - Resubscribe API
  description: >-
    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
  version: 1.0.0
servers:
  - url: https://api-{{0x}}.moengage.com
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
paths:
  /emails/v1.0/bulk-resubscribe:
    post:
      tags:
        - General
      summary: Resubscribe API
      description: "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.\n\n# Authentication\n\nAll Email Resubscription API requests will be authenticated through Basic Authentication. Do the following to generate the Basic Authentication header:\n\n1. Navigate to Settings > APIs > DATA API Settings\n2. Copy the DATA API ID and DATA API KEY\n3. Generate the Authentication string using base64 concatenation of APP ID and API KEY\n    \n\nBasic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '.\n\nDo the following to generate the Auth header:\n\n1. Add a colon after the user name (DATA API ID) and concatenate it with the password (DATA API KEY).\n2. Encode the concatenated string using base64 encoding.\n3. Pass the encoded string in the HTTP authorization header as follows: {\"Authorization\":\" Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U==\"}\n    \n\n# Request Headers\n\n| Key | Mandatory/Optional | Sample Values | Description |\n| --- | --- | --- | --- |\n|   <br>  <br>MOE-APPKEY  <br>  <br> |   <br>  <br>Mandatory  <br>  <br> |   <br>  <br>{\"MOE-APPKEY\": \"APP ID\"}  <br>  <br> |   <br>  <br>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.  <br>  <br>Note: You can also fetch the APP ID from the following navigation: Settings -> App -> General Settings.  <br>  <br> |\n|   <br>  <br>Content-Type  <br>  <br> |   <br>  <br>Mandatory  <br>  <br> |   <br>  <br>{\"Content-Type\": \"application/json\"}  <br>  <br> |   <br>  <br>Set the Content-Type header to application/json for using the Resubscription API.  <br>  <br> |\n|   <br>  <br>Authorization  <br>  <br> |   <br>  <br>Mandatory  <br>  <br> |   <br>  <br>{\"Authorization\": \"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U==\"}  <br>  <br> |   <br>  <br>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.  <br>  <br> |\n\n# Request Body\n\n| Key | Mandatory/Optional | Data Type | Description |\n| --- | --- | --- | --- |\n|   <br>  <br>recipients  <br>  <br> |   <br>  <br>Mandatory  <br>  <br> |   <br>  <br>String Array  <br>  <br> |   <br>  <br>This field contains the email ids of the users who have resubscribed. For example,  <br>  <br>\"recipients\": \\[\"john@example.com\", \"[mike@example.com](mailto:mike@example.com)\"\\]  <br>  <br>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).  <br>  <br> |\n|   <br>  <br>esp  <br>  <br> |   <br>  <br>Mandatory  <br>  <br> |   <br>  <br>String  <br>  <br> |   <br>  <br>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.  <br>  <br> |\n|   <br>  <br>update_esp  <br>  <br> |   <br>  <br>Optional  <br>  <br> |   <br>  <br>Boolean  <br>  <br> |   <br>  <br>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.  <br>  <br> |\n|   <br>  <br>request_id  <br>  <br> |   <br>  <br>Mandatory  <br>  <br> |   <br>  <br>String  <br>  <br> |   <br>  <br>This field contains the value of the identifier for the request.  <br>  <br> |\n\n# Response\n\n| Key | Data Type | Description |\n| --- | --- | --- |\n|   <br>  <br>message  <br>  <br> |   <br>  <br>String  <br>  <br> |   <br>  <br>This field contains a brief description of the request status.  <br>  <br> |\n|   <br>  <br>response_id  <br>  <br> |   <br>  <br>String  <br>  <br> |   <br>  <br>This field contains the unique identifier for the response and is present in the response only when the request is successful.  <br>  <br> |\n|   <br>  <br>error  <br>  <br> |   <br>  <br>JSON Object  <br>  <br> |   <br>  <br>This object is present in the response only in the case of an error.  <br>  <br>\"error\": {  <br>  <br>\"message\": ,  <br>  <br>\"err_code\":  <br>  <br>}  <br>  <br>is a String that contains a brief description of the error for unsuccessful requests.  <br>  <br>is String that contains the error code for unsuccessful requests.  <br>  <br> |\n\n# Response Codes\n\n| Status Code | Request State | Description |\n| --- | --- | --- |\n|   <br>  <br>202  <br>  <br> |   <br>  <br>Success  <br>  <br> |   <br>  <br>This response is returned when the request is processed successfully.  <br>  <br> |\n|   <br>  <br>400  <br>  <br> |   <br>  <br>Bad Request  <br>  <br> |   <br>  <br>This response is returned when the _recipients_ field is not present in the request body.  <br>  <br> |\n|   <br>  <br>401  <br>  <br> |   <br>  <br>Authorization Failure  <br>  <br> |   <br>  <br>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.  <br>  <br> |\n|   <br>  <br>405  <br>  <br> |   <br>  <br>Method not allowed  <br>  <br> |   <br>  <br>This response is returned when the HTTP method of the API is changed from POST to any other (ex.- DELETE, GET, etc).  <br>  <br> |\n|   <br>  <br>415  <br>  <br> |   <br>  <br>Unsupported media type  <br>  <br> |   <br>  <br>This response is returned when the header _Content-Type_ is not provided/is not supported.  <br>  <br> |\n|   <br>  <br>429  <br>  <br> |   <br>  <br>Rate Limit Breach  <br>  <br> |   <br>  <br>This response is returned when the number of requests has exceeded the rate limit.  <br>  <br> |\n|   <br>  <br>500  <br>  <br> |   <br>  <br>Internal Server Error  <br>  <br> |   <br>  <br>This response is returned when the system runs into an unexpected error.  <br>  <br> |\n\n# Supported ESPs\n\nThe Resubscription API supports only SendGrid.\n\n# Rate Limit\n\n| Rate Limit | 10 requests per minute |  \n| Allowed Volume | 14.4K requests per day |  \n| Payload size | 100 recipient email addresses per request |\n\n# FAQs\n\n**1\\. What happens when the update_esp field is not sent in the request?**\n\nWe will automatically call the ESP to remove the recipient email addresses sent in the request from their suppression list.\n\n**2\\. Which attribute stores the user’s email address in MoEngage?**  \nThis 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.  \nThe 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.\n\n**3\\. What happens when there are multiple connectors enabled for an account?**  \nThe 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.\n\n**4\\. What happens when an ESP other than SENDGRID is mentioned in the request?**  \nIf 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).\n\n**5\\. What happens if a resubscription request is performed when the ESP is changed in the MoEngage Dashboard?**\n\nWhen 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."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                recipients:
                  - example@domain.com
                update_esp: true
                esp: SENDGRID
                request_id: uniqueidentifier
      security:
        - basicAuth: []
      parameters:
        - name: MOE-APPKEY
          in: header
          schema:
            type: string
          example: '{{DATA API ID}}'
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
