Teams & Collaboration

Base URL: https://api.inboxical.com/v1

Create a team

POST /teams

Request body

Field	Type	Required	Description
`name`	string	Yes	Team name

Example

curl -X POST https://api.inboxical.com/v1/teams \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Backend QA" }'

Response 201

{
  "id": "team_abc123",
  "name": "Backend QA",
  "owner_id": "user_xyz",
  "members": [
    {
      "user_id": "user_xyz",
      "user_name": "Jane Doe",
      "user_email": "[email protected]",
      "role": "owner",
      "joined_at": "2026-03-21T12:00:00Z"
    }
  ],
  "created_at": "2026-03-21T12:00:00Z"
}

The creating user is automatically added as the team owner.

Errors

Status	Reason
`400`	Team name is required
`403`	Plan does not support teams, or team limit reached

List teams

GET /teams

Returns all teams where the authenticated user is an owner or member.

curl https://api.inboxical.com/v1/teams \
  -H "Authorization: Bearer $JWT_TOKEN"

Response 200 — an array of team objects (same shape as the create response).

Get a team

GET /teams/:id

Returns a single team with its members. You must be a member of the team to access it.

curl https://api.inboxical.com/v1/teams/team_abc123 \
  -H "Authorization: Bearer $JWT_TOKEN"

Update a team

PUT /teams/:id

Renames a team. Owner only.

Request body

Field	Type	Required	Description
`name`	string	Yes	New team name

curl -X PUT https://api.inboxical.com/v1/teams/team_abc123 \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Frontend QA" }'

Errors

Status	Reason
`403`	Only the team owner can update the team

Delete a team

DELETE /teams/:id

Permanently deletes the team and removes all member associations. Inboxes previously assigned to the team are unlinked but not deleted. Owner only.

curl -X DELETE https://api.inboxical.com/v1/teams/team_abc123 \
  -H "Authorization: Bearer $JWT_TOKEN"

Response 200

{
  "message": "Team deleted"
}

Invite a member

POST /teams/:id/invite

Sends an invite to a user by email. Owner or admin only.

Request body

Field	Type	Required	Description
`email`	string	Yes	Email address to invite
`role`	string	No	`"member"` (default) or `"admin"`

Example

curl -X POST https://api.inboxical.com/v1/teams/team_abc123/invite \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "role": "admin" }'

Response 201

{
  "id": "invite_abc123",
  "token": "raw-invite-token...",
  "email": "[email protected]",
  "role": "admin",
  "expiresAt": "2026-03-28T12:00:00Z"
}

Invite tokens expire after 7 days.

Errors

Status	Reason
`403`	Caller is not an owner/admin, or member limit reached
`409`	User is already a member, or an active invite already exists

Accept an invite

POST /teams/invites/accept

Accepts a team invite using the token from the invite response. The authenticated user’s email must match the invite email.

Request body

Field	Type	Required	Description
`token`	string	Yes	Invite token

curl -X POST https://api.inboxical.com/v1/teams/invites/accept \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "token": "raw-invite-token..." }'

Response 200 — returns the full team object with members.

Errors

Status	Reason
`400`	Invalid or expired invite token
`403`	Invite was sent to a different email
`409`	Already a member of this team

Remove a member

DELETE /teams/:id/members/:userId

Removes a member from the team. Owner or admin only. The team owner cannot be removed.

curl -X DELETE https://api.inboxical.com/v1/teams/team_abc123/members/user_bob \
  -H "Authorization: Bearer $JWT_TOKEN"

Response 200

{
  "message": "Member removed"
}

Errors

Status	Reason
`400`	Cannot remove the team owner
`403`	Caller is not an owner or admin
`404`	Team or member not found

Roles

Role	Permissions
owner	Full control — update team, invite, remove members, delete team
admin	Invite and remove members
member	Access shared team resources

Team limits by plan

Plan	Max teams	Max members per team
Free	0	0
Starter	1	3
Pro	5	10
Business	Unlimited	Unlimited