> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xem.email/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for Xem - Email automation and analytics platform

# API Reference

Welcome to the Xem API reference. This is your complete guide to integrating with our email automation and analytics platform.

## Quick Start

The Xem API is RESTful and follows standard HTTP conventions. All requests should be made to `https://api.xem.email` and include proper authentication headers.

```bash theme={"dark"}
curl -X GET "https://api.xem.email/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Authentication

Most API endpoints require authentication. You can authenticate using:

* **Bearer Token**: Include your API key in the Authorization header
* **JWT Token**: For user-specific operations

```bash theme={"dark"}
# Using API Key
Authorization: Bearer pk_live_your_api_key_here

# Using JWT Token  
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## Base URL

```
https://api.xem.email
```

## API Versioning

The API is versioned using the URL path. Currently, we support:

* **v1**: Current stable version (recommended)

```
https://api.xem.email/api/v1/
```

## Response Format

All API responses are returned in JSON format with the following structure:

```json theme={"dark"}
{
  "data": {
    // Response data here
  },
  "message": "Success message",
  "status": "success"
}
```

## Error Handling

Errors follow a consistent format:

```json theme={"dark"}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Email format is invalid"
    }
  },
  "status": "error"
}
```

## Rate Limiting

Most endpoints allow 100 requests per minute per IP address. Sign-in, registration and password-reset endpoints are stricter. See [Rate limiting](https://docs.xem.email/rate-limiting.md) for every limit and for retry advice.

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

## API Endpoints

### Authentication

* [Register User](https://docs.xem.email/auth/register.md) - Create a new user account
* [Login User](https://docs.xem.email/auth/login.md) - Authenticate and get JWT token
* [Google OAuth](https://docs.xem.email/api-reference/auth/authenticate-with-google.md) - Authenticate with Google
* [Refresh Token](https://docs.xem.email/api-reference/auth/refresh-access-token.md) - Refresh expired JWT token
* [Password Reset](https://docs.xem.email/api-reference/auth/request-password-reset.md) - Request password reset
* [Invite User](https://docs.xem.email/api-reference/auth/invite-a-user-to-join-a-team.md) - Invite user to team

### User Management

* [Get Current User](https://docs.xem.email/api-reference/users/get-current-user.md) - Get authenticated user details
* [List Users](https://docs.xem.email/api-reference/users/list-all-users.md) - List all users in team
* [Get User](https://docs.xem.email/api-reference/users/get-user-details.md) - Get specific user details
* [Update User](https://docs.xem.email/api-reference/users/update-user-details.md) - Update user information
* [Delete User](https://docs.xem.email/api-reference/users/delete-user.md) - Delete user account

### Email Operations

* [Send Email](https://docs.xem.email/api-reference/email/send-an-email.md) - Send transactional emails
* Email Templates - Manage email templates
* Campaigns - Create and manage email campaigns

### Analytics

* [Campaign Analytics](https://docs.xem.email/analytics/campaign.md) - Campaign performance metrics
* [Email Analytics](https://docs.xem.email/api-reference/get-email-analytics.md) - Email delivery and engagement
* [Audience Insights](https://docs.xem.email/api-reference/get-audience-insights.md) - Subscriber behavior analysis
* [Team Overview](https://docs.xem.email/api-reference/get-team-overview.md) - Team-wide performance summary
* [Trend Analysis](https://docs.xem.email/api-reference/get-trend-analysis.md) - Historical performance trends
* [Click Heatmap](https://docs.xem.email/api-reference/get-click-heatmap.md) - Visual click tracking data

### File Management

* [Upload File](https://docs.xem.email/api-reference/files/upload-a-file.md) - Upload files for email attachments

### Subscriptions & Billing

* [Get Plans](https://docs.xem.email/api-reference/plans/get-all-plans.md) - View available subscription plans
* [Create Subscription](https://docs.xem.email/subscriptions/create.md) - Start a new subscription
* [Get Features](https://docs.xem.email/api-reference/subscriptions/get-enabled-features.md) - View enabled features
* [Manage Subscription](https://docs.xem.email/api-reference/subscriptions/get-subscription-management-portal-url.md) - Access billing portal

### Email Tracking

* [Open Tracking](https://docs.xem.email/tracking/open.md) - Track email opens
* [Click Tracking](https://docs.xem.email/api-reference/handle-click-tracking.md) - Track link clicks

## SDKs & Libraries

Xem has two official SDKs:

* **Node.js and TypeScript**: `npm install @xem.email/sdk` ([example](https://docs.xem.email/examples/nodejs.md))
* **Go**: `go get github.com/mailxem/mail/sdk-go`

From any other language, call the REST API with the `X-API-Key` header.

## Webhooks

Configure webhooks to receive real-time notifications:

* **Email Events**: Opens, clicks, bounces, complaints
* **Campaign Events**: Started, completed, paused
* **Subscription Events**: Created, updated, cancelled

## Support

Need help integrating with our API?

* **Documentation**: Browse our guides and examples
* **Community**: Join our [Discord server](https://discord.gg/MXQgb9s5bA)
* **Support**: Email us at [team@xem.email](mailto:team@xem.email)
* **GitHub**: Check our [open source repositories](https://github.com/mailxem/mail)

## Changelog

Stay updated with our [API changelog](https://docs.xem.email/changelog) for the latest features, improvements, and breaking changes.

***

Ready to get started? Check out our [quickstart guide](https://docs.xem.email/guides/quickstart.md) or dive into the [authentication docs](https://docs.xem.email/authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.