Subscriber Opt In API

Overview

Use the Subscriber Optin API to filter, sort and retrieve subscriber's email status and optin information to keep another system in sync. This is an OData endpoint, and it will support the OData query language. More information about this can be found at odata.org

Related APIs: 


Possible Response Codes

  • 200 (OK). The request has been successfully executed.
  • 400 (Bad Request). The request could not be parsed successfully.
  • 401 (Unauthorized). The token is missing or invalid.
  • 500 (Internal Server Error). An internal error has occurred. 

Authentication

The OData API requires authentication. The GET request will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token. 

Authenticate message header example:

Authenticate: Avala-Api {username}:{token}

Query Information

Endpoint

GET https://{baseurl}/odata/v2/SubscriberOptIn

Filter Options

Name Values Description
SubscriberStatus Subscribed
Unsubscribed
Unsubscribed-Partial
Filters by Subscriber Status
EmailDeliverabilityStatus Active
Soft Bounce
Hard Bounce
Filters by Email Deliverability Status
Email String Filters by specific email
OptInDate yyyy-MM-ddThh:mm:ssZ Filters by OptInDate
IsOptedIn Boolean Filters by subscribers opted in or not
CreateDate yyyy-MM-ddThh:mm:ssZ Filters by CreateDate
UpdateDate yyyy-MM-ddThh:mm:ssZ Filters by UpdateDate

For filter formatting in OData, please reference this page and navigate to section 4.5. Filter System Query Option to see operators and examples.

Sample Queries

OptInDate Between Two Dates

GET https://{baseurl}/odata/v2/SubscriberOptIn?$filter=OptInDate gt 2017-10-13T13:29:51-05:00 and OptInDate lt 2017-10-19T13:29:51-05:00
Authenticate: Avala-Api {username}:{token}


IsOptedIn is True

GET https://{baseurl}/odata/v2/SubscriberOptIn?$filter=IsOptedIn eq true
Authenticate: Avala-Api {username}:{token}


Email Address Equals

GET https://{baseurl}/odata/v2/SubsriberOptIn?$filter=Email eq 'a@b.com'
Authenticate: Avala-Api {username}:{token}


SubscriberStatus Equals

GET https://{baseurl}/odata/v2/SubsriberOptIn?$filter=SubscriberStatus eq 'Subscribe'
Authenticate: Avala-Api {username}:{token}

Sample Response

Request: 

GET https://{baseurl}/odata/v2/SubsriberOptIn?$filter=Email eq 'test@test.com'
Authenticate: Avala-Api {username}:{token}

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 380
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
Expires: -1
Server: Microsoft-IIS/10.0
api-supported-versions: 2.0
OData-Version: 4.0
X-AspNet-Version: 4.0.30319
Request-Context: appId=cid-v1:16f8d7a5-63fa-4ed2-acb1-7c4d1976984b
Access-Control-Expose-Headers: Request-Context
X-Powered-By: ASP.NET
Date: Wed, 25 Mar 2020 22:23:01 GMT
Connection: close

{
  "@odata.context": "https://{baseurl}/odata/V2/$metadata#SubscriberOptIn",
  "value": [
    {
      "Id": 1519,
      "Email": "test@test.com",
      "IsOptedIn": false,
      "IpAddress": null,
      "OptInDate": null,
      "OptInSource": null,
      "CountryCode": "US",
      "CreateDate": "2018-10-11T00:33:24.247-05:00",
      "UpdateDate": "2019-08-06T04:00:27.457-05:00",
      "EmailDeliverabilityStatus": "Active",
      "SubscriberStatus": "Subscribed"
    }
  ]
}