Subscribers

Subscribers are an essential part of Protocol — they are the containers for the messages between you, your contacts, and groups. On this page, we’ll dive into the different subscribers endpoints you can use to manage conversations programmatically. We'll look at how to query, create, update, and delete conversations.

The subscribers model

The subscribers model contains all the information about the conversations between you and your contacts. In addition, conversations can also be group-based with more than one contact, they can have a pinned message, and they can be muted.

Properties

Name
id
Type
string
Description
Unique identifier for the subscribers.
Name
name
Type
string
Description
Name of the subscriber.
Name
email
Type
string
Description
Email of the subscriber.
Name
created_at
Type
timestamp
Description
Timestamp of when the subscribers was created.
Name
updated_at
Type
timestamp
Description
Timestamp of subscriber update time.

GET/v1/conversations

List all conversations

This endpoint allows you to retrieve a paginated list of all your conversations. By default, a maximum of ten conversations are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of subscribers returned.

Request

curl -G https://api.bloghunch.com/app/{subdomain}/subscribers \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "meta": {
    "total": 11,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1,
    "first_page": 1,
    "first_page_url": "/?page=1",
    "last_page_url": "/?page=1",
    "next_page_url": null,
    "previous_page_url": null
  },
  "data": [
    {
      "id": 3,
      "name": "John Doe",
      "email": "johndoe@test.com",
      "avatar": "https://www.gravatar.com/avatar/70775083d3ae2a1c386d1faa60f73ebd"
    },
    ...
  ]
}

POST/subscribers

Create a subscriber

This endpoint allows you to create a new subscriber.

Required attributes

Name
email
Type
string
Description
The email address of the subscriber.

Optional attributes

Name
name
Type
string
Description
The name of the subscriber.

Request

curl -X POST https://api.bloghunch.com/app/{subdomain}/subscribers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe"
  }'

Response

{
  "status": "success",
  "message": "Subscriber created",
  "subscriber": {
    "id": 4,
    "name": "Jane Doe",
    "email": "jane@example.com"
  }
}

PUT/subscribers/{id}

Update a subscriber

This endpoint allows you to update an existing subscriber.

Optional attributes

Name
name
Type
string
Description
The updated name of the subscriber.
Name
email
Type
string
Description
The updated email of the subscriber.

Request

curl -X PUT https://api.bloghunch.com/app/{subdomain}/subscribers/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith"
  }'

Response

{
  "status": "success",
  "message": "Subscriber updated",
  "subscriber": {
    "id": 4,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
}

DELETE/subscribers/{id}

Delete a subscriber

This endpoint allows you to delete an existing subscriber.

Request

curl -X DELETE https://api.bloghunch.com/app/{subdomain}/subscribers/{id} \
  -H "Authorization: Bearer {token}"

Response

{
  "status": "success",
  "message": "Subscriber deleted"
}