Skip to main content
This page demonstrates practical workflows and production best practices for using the Team API effectively.

​
Common Use Cases

Here are brief examples of common workflows using the Team API.

​
Domain Management Workflow

Add a domain, verify DNS records, and attach it to a project: 
# 1. Add domain
curl -X POST "https://api.lettermint.co/v1/domains" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# 2. Verify DNS records
curl -X POST "https://api.lettermint.co/v1/domains/{domainId}/dns-records/verify" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN"

# 3. Attach to project
curl -X PUT "https://api.lettermint.co/v1/domains/{domainId}/projects" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projects": ["projectId"]}'
Domain verification status showing DNS records in the dashboard

​
Project and Route Setup

Create a project, add a route, and configure a webhook: 
# 1. Create project
curl -X POST "https://api.lettermint.co/v1/projects" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

# 2. Create route
curl -X POST "https://api.lettermint.co/v1/projects/{projectId}/routes" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Transactional"}'

# 3. Add webhook
curl -X POST "https://api.lettermint.co/v1/webhooks" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"route_id": "routeId", "url": "https://api.example.com/webhooks", "events": ["delivered", "bounced"]}'
Project and route overview in the dashboard

​
Message Monitoring

List messages with filters and retrieve detailed event history: 
# List messages with filters
curl -X GET "https://api.lettermint.co/v1/messages?status=delivered&page[size]=50" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN"

# Get message events
curl -X GET "https://api.lettermint.co/v1/messages/{messageId}/events" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN"
The Messages API is read-only. Use the Team API to monitor delivery, not to send emails (use Project tokens for sending).

​
Suppression Management

Add email addresses to the suppression list and remove them when needed: 
# Add suppression
curl -X POST "https://api.lettermint.co/v1/suppressions" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "reason": "hard_bounce"}'

# List suppressions
curl -X GET "https://api.lettermint.co/v1/suppressions?page[size]=50" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN"

# Remove suppression
curl -X DELETE "https://api.lettermint.co/v1/suppressions/{suppressionId}" \
  -H "Authorization: Bearer YOUR_TEAM_TOKEN"

​
Best Practices

​
Security Recommendations

  • Store tokens securely: Use environment variables or secrets managers (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Grant minimal abilities: Only assign the abilities each token needs to perform its function
  • Rotate tokens regularly: Regenerate tokens periodically, especially for long-running integrations
  • Monitor token usage: Check the “Last used” timestamp in the dashboard to identify inactive or compromised tokens
  • Delete unused tokens: Remove tokens that are no longer needed

​
Operational Recommendations

  • Implement error handling: Always handle HTTP errors gracefully with exponential backoff for retries
  • Respect rate limits: Track X-RateLimit-Remaining headers and implement request queuing if needed
  • Handle pagination: Use cursor-based pagination for large result sets
  • Log request metadata: Store request IDs and timestamps for debugging
  • Use descriptive names: Name tokens and resources clearly to aid in debugging and auditing
Team API tokens have broad access to your team resources. Treat them with the same care as passwords and never expose them in client-side code, public repositories, or logs.

​
API Reference

Explore the complete API documentation for detailed endpoint information:

Team

View and update team settings, usage, and members

Domains

Manage verified sending domains and DNS records

Projects

Create and manage projects and routes

Webhooks

Configure webhook endpoints and delivery settings

Messages

Access message history and delivery events

Suppressions

Manage bounce and complaint suppression lists

​
Next Steps