Skip to main content
POST
/
api
/
services
Create Service
curl --request POST \
  --url https://api.example.com/api/services \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "name": "<string>",
  "email": "<string>",
  "color": "<string>",
  "signature": "<string>",
  "document": "<string>"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "email": "<string>",
  "color": "<string>",
  "signature": "<string>",
  "document": "<string>",
  "categories": [
    {}
  ],
  "unreadCount": 123,
  "createdAt": "<string>"
}
Creates a new Gmail service account in the system. The service can be connected to Gmail later via the OAuth flow.

​
Authentication

Requires a valid session with a user email. User must be authenticated via NextAuth.
Only authenticated users with valid email addresses can create services.

​
Request body

​
id
string
Optional custom identifier for the service. If not provided, generates service-{timestamp}
​
name
string
required
Display name for the service (e.g., “Customer Support”, “Sales Team”)
​
email
string
Gmail email address. If not provided or invalid, uses a placeholder {id}@pending.local
​
color
string
default:"#3b5bdb"
Hex color code for UI display
​
signature
string
default:""
Email signature for outbound messages
​
document
string
default:""
Documentation or notes about this service

​
Response

Returns the created service object.

​
Response fields

​
id
string
required
Unique identifier for the created service
​
name
string
required
Display name of the service
​
email
string
required
Email address (or placeholder if not provided)
​
color
string
required
Hex color code for UI display
​
signature
string
required
Email signature text
​
document
string
required
Documentation text
​
categories
array
required
Empty array (categories are added separately)
​
unreadCount
number
required
Always 0 for newly created services
​
createdAt
string
required
ISO 8601 timestamp of creation

​
Response examples

{
  "id": "service-1709308800000",
  "name": "Customer Support",
  "email": "[email protected]",
  "color": "#3b5bdb",
  "signature": "Best regards,\nSupport Team",
  "document": "Handle all customer inquiries",
  "categories": [],
  "unreadCount": 0,
  "createdAt": "2026-03-01T12:00:00.000Z"
}

​
Code examples

curl --request POST \
  --url 'https://your-domain.com/api/services' \
  --cookie 'authjs.session-token=YOUR_SESSION_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Customer Support",
    "email": "[email protected]",
    "color": "#3b5bdb",
    "signature": "Best regards,\nSupport Team",
    "document": "Handle all customer inquiries"
  }'

​
Validation rules

  • name is required and must be provided in the request body
  • email is normalized to lowercase and validated for @ presence
  • If email is invalid or missing, a placeholder email is generated
  • All other fields have default values and are optional
After creating a service, connect it to Gmail using the Connect endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us