The Scope Simple Address Interface (SAI) allows clients of Scope to keep their recipient records on their own infrastructure. Before each newsletter send-out the Scope system will retrieve the list of recipient records and send the emails to these recipients. These records are never persisted on the Scope infrastructure.

The entire process is based on the two simple endpoints that are described below.

General Assumptions

Access through SSL only.
All endpoints are protected by HTTP Basic Authentication.
Ideally the newly created endpoints would be versioned (by a version number in the URL). By doing this, each party would gain flexibility and the deployments, changes would be less coupled

Endpoint: Providing the List of Recipients

Scope executes a HTTP GET request to a provider-specific URL. Different lists are distinguished by URLs or query parameters.

Response Data Format

JSON list of recipient objects:

[
{
    "email": "hans@muster.com",
    "firstName": "Hans",
    "lastName": "Muster"
},
...
]

Additional Query Arguments

Argument-Name	Possible Values	Mandatory?	Description
test	[true, false]	No, if omitted the system assumes the value to be false	If set to true, the system only returns a test subset of recipients

Assumptions

The list does not include any duplicate records (emails are unique).
The email field is always filled with a valid email address. If the email address is not valid, the record will not be considered.
If the values for firstName or lastName are not available for a record, the field is set to the value "null" or a blank string. The fields are never left out.

Server Responses / Feedback

HTTP 200 and the expected list of objects in a successful case.
Non HTTP 200 responses that include an error message in all other cases.

Endpoint: Unsubscribing a Single Recipient

Scope executes a HTTP POST request to a provider specific URL. The POST body contains a JSON object as follows:

{
    "email": "hans@muster.com"
}

Server Responses / Feedback

HTTP 200 with the following response object:

{
    "success": true
}

The "success" field is set to "true", if the recipient has been found in the records and has been unsubscribed. The same response is expected for repeated requests or cases where the recipient was already unsubscribed.

The "success" field is set to "false" if the recipient has not been found in the records.

Non HTTP 200 responses that include an error message in all other cases.