Home
Home
Analytics
Help
post

/v5/event/unsubscribe

Sometimes it may be desirable to process an unsubscribe that generates from outside of the MessageGears platform but still send that event into the MessageGears system for reporting purposes. This API is designed to do that using one of two methods:

1. Using ${Gears.recipientLinkToken()} inside a message sent through the MessageGears system
2. Sending relevant details about the unsubscribe directly to the API

For the first scenario, one could include ${Gears.recipientLinkToken()} inside a message using one of our submission API calls. For instance, you may have a system designed to handle unsubscribes on your own servers, and you simply needed a token to identify the recipient and the mailing that prompted the unsubscribe. To handle that, you could append the ${Gears.recipientLinkToken()} onto your unsubscribe link and retrieve the value of the token and submit it back to MessageGears using this API.

Another scenario is that the unsubscribe may not have been tied to any message sent by MessageGears at all and came from some other source. However, you would still like to send the unsubscribe into the MessageGears system so that it comes through your Real Time Event Feed.

When choosing to submit a request using a token, you will receive complete reporting for the unsubscribe. This includes your Analytics, Real Time Event Feed, and any aggregation files that are available for download. In each, the event will be associated with the job that sent the mailing thanks to the information from the token.

When choosing to submit a request without using the token, however, you are limited to only receiving the event on the Real Time Event feed. In both cases, it is expected that you honor the unsubscribe within your own system to prevent sending unwanted messages to recipients who have requested to be unsubscribed

Request Parameters

1 Header

Request Body

When submitting to this API, the following rules apply:

  1. Either a token is required or AT LEAST ONE of recipientId or emailAddress
  2. You may not provide a token with a recipientId or emailAddress
  3. If no token is provided, then an accountId must be provided
  4. If a token is provided, a jobCategory cannot be provided
2 Examples
Schema
object
userAgent
string
ipAddress
string
token
string
emailAddress
string
recipientId
string
accountId
string
jobCategory
string

Useful for tagging unsubscribes that generate outside of the MessageGears system

Responses

Schema
object

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
host