Skip to main content
GET
/
api
/
services
List Services
curl --request GET \
  --url https://api.example.com/api/services
{
  "id": "<string>",
  "name": "<string>",
  "email": "<string>",
  "color": "<string>",
  "gmailConnected": true,
  "signature": "<string>",
  "document": "<string>",
  "unreadCount": 123,
  "categories": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "<string>",
      "textColor": "<string>"
    }
  ]
}
Returns a list of all Gmail service accounts configured in the system, including their connection status, unread counts, and associated categories.

​
Authentication

Requires a valid session. User must be authenticated via NextAuth.
This endpoint uses session-based authentication. Ensure you have a valid session cookie.

​
Response

Returns an array of service objects with their configurations and statistics.

​
Response fields

​
id
string
required
Unique identifier for the service account
​
name
string
required
Display name of the service account
​
email
string
required
Gmail email address associated with this service
​
color
string
required
Hex color code for UI display (e.g., #3b5bdb)
​
gmailConnected
boolean
required
Whether the service has valid Gmail OAuth tokens
​
signature
string
required
Email signature text for outbound messages
​
document
string
required
Additional documentation or notes for this service
​
unreadCount
number
required
Number of unread emails in inbox for this service
​
categories
array
required
Array of category objects associated with this service

​
Response example

[
  {
    "id": "service-1234567890",
    "name": "Customer Support",
    "email": "[email protected]",
    "color": "#3b5bdb",
    "gmailConnected": true,
    "signature": "Best regards,\nSupport Team",
    "document": "Handle all customer inquiries",
    "unreadCount": 12,
    "categories": [
      {
        "id": "cat-urgent",
        "name": "Urgent",
        "color": "#ff6b6b",
        "textColor": "#ffffff"
      },
      {
        "id": "cat-billing",
        "name": "Billing",
        "color": "#51cf66",
        "textColor": "#000000"
      }
    ]
  },
  {
    "id": "service-1234567891",
    "name": "Sales",
    "email": "[email protected]",
    "color": "#748ffc",
    "gmailConnected": false,
    "signature": "",
    "document": "",
    "unreadCount": 0,
    "categories": []
  }
]

​
Code examples

curl --request GET \
  --url 'https://your-domain.com/api/services' \
  --cookie 'authjs.session-token=YOUR_SESSION_TOKEN'

​
Implementation details

The endpoint performs the following operations:
  1. Validates user session via requireSession()
  2. Fetches all Gmail accounts from the database
  3. Retrieves all categories
  4. Calculates unread counts by querying email threads with status='inbox' and isRead=false
  5. Maps data into response format with categories grouped by account
The gmailConnected field is derived from the presence of a refreshToken in the database. Services without a refresh token cannot sync emails.

Build docs developers (and LLMs) love

Get started for freeTalk to us