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:
- To create a subscriber record and add to a list in Aimbase use the Subscriber Service API.
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 |
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" } ] }