Copy page

Team API

Reference

This page covers advanced topics you'll need for production use of the Team API.

Understanding Token Abilities

Team API tokens use a granular permission system based on abilities. Each token can have one or more abilities that control which resources it can access and which operations it can perform.

Read vs Write Scopes

Abilities are organized into read and write scopes:

• Read abilities (e.g., read:team, read:domains) allow tokens to view resources and retrieve information
• Write abilities (e.g., write:projects, write:webhooks) allow tokens to create, update, and delete resources

Write abilities do not imply read access. Grant each explicit ability needed by the integration.

The * ability grants full access to standard Team API resources. Use explicit read and write abilities instead unless an integration genuinely needs every resource.

write:member_assignments is intentionally separate. It can change a member's effective access, so it must be added explicitly by an Owner and requires read:members. The * ability does not imply it.

Available Abilities

For a complete list of available abilities and their descriptions, see the Token abilities table in the Team API tokens guide.

Insufficient Permissions

If a token attempts an operation without the required ability, the API returns a 403 Forbidden error:

Code
{
  "error": {
    "code": "FORBIDDEN",
    "message": "This token does not have the required abilities to perform this action."
  }
}

Working with Rate Limits

The Team API implements rate limiting to ensure fair usage and platform stability. Different rate limits apply based on the operation type.

Rate Limit Tiers

• Read operations: 300 requests per minute (GET endpoints)
• Write operations: 60 requests per minute (POST, PUT, DELETE endpoints)
• Special endpoints: 3-10 requests per minute, including project token rotation, DNS verification, webhook tests, and webhook secret regeneration

Rate Limit Headers

Every API response includes headers showing your current rate limit status:

Code
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 1705843200

Handling Rate Limit Errors

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

Code
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retry_after": 42
  }
}

Error Handling

The Team API uses standard HTTP status codes to indicate the success or failure of requests.

Common Status Codes

Status	Description
200 OK	Request succeeded
201 Created	Resource created successfully
400 Bad Request	Invalid request format or parameters
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Token lacks required abilities
404 Not Found	Resource does not exist
409 Conflict	The requested change conflicts with current resource state or a protected invariant
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error (contact support)

Error Response Format

All error responses follow a consistent format:

Code
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Validation Errors

Validation errors (422) include detailed field-level errors:

Code
{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain has already been taken."],
    "name": ["The name field is required."]
  }
}

SDK Notes

Official SDKs expose the Team API through team-scoped clients such as Lettermint.api(...), Lettermint\Lettermint::api(...), and lettermint.NewAPI(...). These clients use bearer authentication and return typed responses where the language supports it.

• Pass pagination and filter values as query parameters, for example page[size], page[cursor], or filter[search].
• Message source, html, and text endpoints return raw strings instead of JSON response objects.
• Use Project API tokens only with the Sending API. Team API clients require Team API tokens.

Next Steps

• Manage member access - Assign roles and project access from an integration
• Use Cases & Best Practices - Explore common workflows and production guidance
• API Reference - View complete Team API documentation