Subscribers
Index
Retrieve a paginated list of all subscribers.
Usage
Endpoint
GET /api/v1/subscribers
Expected Response Code
200
Response Fields
- data:
array<object>- id:
int - first_name:
string - last_name:
string - email:
string - unsubscribed_at:
datetime - created_at:
datetime - updated_at:
datetime
- id:
Sample Request
GET /api/v1/subscribers HTTP/1.1
Host: sendportal.local
Authorization: Bearer 9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ
Accept: application/json
Sample Response
{
"data": [
{
"id": 1,
"first_name": "Test",
"last_name": "Subscriber",
"email": "[email protected]",
"unsubscribed_at": null,
"created_at": "2020-03-23 13:44:09",
"updated_at": "2020-03-23 13:44:09"
},
{
"id": 2,
"first_name": "Test",
"last_name": "Subscriber Two",
"email": "[email protected]",
"unsubscribed_at": "2020-08-02 08:07:08",
"created_at": "2020-03-23 13:50:39",
"updated_at": "2020-03-23 13:50:39"
}
],
"links": {
"first": "<https://sendportal.local/api/v1/subscribers?page=1>",
"last": "<https://sendportal.local/api/v1/subscribers?page=1>",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "<https://sendportal.local/api/v1/subscribers>",
"per_page": 25,
"to": 2,
"total": 2
}
}
Show
Retrieve the details of a single subscriber, including its tags.
Usage
Endpoint
GET /api/v1/subscribers/{subscriberId}
Expected Response Code
200
Response Fields
- data:
object- id:
int - first_name:
string - last_name:
string - email:
string - tags:
array<object>- id:
int - string:
string - created_at:
datetime - updated_at:
datetime
- id:
- unsubscribed_at:
datetime - created_at:
datetime - updated_at:
datetime
- id:
Sample Request
GET /api/v1/subscribers/1 HTTP/1.1
Host: sendportal.local
Authorization: Bearer 9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ
Accept: application/json
Sample Response
{
"data": {
"id": 1,
"first_name": "Test",
"last_name": "Subscriber",
"email": "[email protected]",
"tags": [
{
"id": 1,
"name": "Test Tag",
"created_at": "2020-03-23 12:44:14",
"update_at": "2020-03-23 12:44:14"
}
],
"unsubscribed_at": null,
"created_at": "2020-03-23 13:44:09",
"updated_at": "2020-03-23 13:44:09"
}
}
Store
Create a new subscriber, optionally including tags that should be assigned to them; or update an existing subscriber based on their email address, optionally including the tags that should be assigned to them.
This endpoint is overloaded to allow for the update of existing subscribers based on the email address provided in the request. This allows for a workflow where the caller of the API needn't know whether the subscriber is already created; this eliminates the need for developers to create different logical paths in their application and also allows subscribers to be updated without prior knowledge of their internal SendPortal ID.
The rules for creating new subscribers or updating existing subscribers are as follows:
- If the email address is not currently used for a subscriber in the workspace, then a new subscriber will be created using the email address, name and tags provided
- If the email address is currently used by a subscriber in the workspace, then that subscriber will be updated using the name and tags provided
Usage
Endpoint
POST /api/v1/subscribers
Expected Response Code
201
Request Fields
- first_name:
string(optional) - last_name:
string(optional) - email:
string - unsubscribed_at:
datetime(optional) - tags:
array<int>(optional)
Response Fields
- data:
object- id:
int - first_name:
string - last_name:
string - email:
string - tags:
array<object>- id:
int - name:
int - created_at:
datetime - updated_at:
datetime
- id:
- unsubscribed_at:
datetime - created_at:
datetime - updated_at:
datetime
- id:
Sample Request
POST /api/v1/subscribers HTTP/1.1
Host: sendportal.local
Authorization: Bearer 9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ
Accept: application/json
Content-Type: application/json
{
"first_name": "Test",
"last_name": "Subscriber Two",
"email": "[email protected]",
"tags": [1]
}
Sample Response
{
"data": {
"id": 2,
"first_name": "Test",
"last_name": "Subscriber two",
"email": "[email protected]",
"tags": [
{
"id": 1,
"name": "Test Tag",
"created_at": "2020-03-23 12:44:14",
"update_at": "2020-03-23 12:44:14"
}
],
"unsubscribed_at": null,
"created_at": "2020-03-24 10:43:08",
"updated_at": "2020-03-24 10:43:08"
}
}
Update
Endpoint
PUT /api/v1/subscribers/{subscriberId}
Expected Response Code
200
Description
Update the details of the given subscriber.
Request Fields
- first_name:
string(optional) - last_name:
string(optional) - email:
string - unsubscribed_at:
datetime(optional)
Response Fields
- data:
object- id:
int - first_name:
string - last_name:
string - email:
string - unsubscribed_at:
datetime - created_at:
datetime - updated_at:
datetime
- id:
Sample Request
PUT /api/v1/subscribers/2 HTTP/1.1
Host: sendportal.local
Authorization: Bearer 9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ
Accept: application/json
Content-Type: application/json
{
"first_name": "Test",
"last_name": "Subscriber Two Updated",
"email": "[email protected]",
"tags": [1]
}
Sample Response
{
"data": {
"id": 2,
"first_name": "Test",
"last_name": "Subscriber Two Updated",
"email": "[email protected]",
"unsubscribed_at": null,
"created_at": "2020-03-24 10:43:08",
"updated_at": "2020-03-24 10:50:20"
}
}
Delete
Delete the given subscriber.
Usage
Endpoint
DELETE /api/v1/subscribers/{subscriberId}
Expected Response Code
204
Sample Request
DELETE /api/v1/subscribers/2 HTTP/1.1
Host: sendportal.local
Authorization: Bearer 9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ
Accept: application/json