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.

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

# 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:

{
  "data": {
    // Response data here
  },
  "message": "Success message",
  "status": "success"
}

Error Handling

Errors follow a consistent format:

{
  "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 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 - Create a new user account
Login User - Authenticate and get JWT token
Google OAuth - Authenticate with Google
Refresh Token - Refresh expired JWT token
Password Reset - Request password reset
Invite User - Invite user to team

User Management

Get Current User - Get authenticated user details
List Users - List all users in team
Get User - Get specific user details
Update User - Update user information
Delete User - Delete user account

Email Operations

Send Email - Send transactional emails
Email Templates - Manage email templates
Campaigns - Create and manage email campaigns

Analytics

Campaign Analytics - Campaign performance metrics
Email Analytics - Email delivery and engagement
Audience Insights - Subscriber behavior analysis
Team Overview - Team-wide performance summary
Trend Analysis - Historical performance trends
Click Heatmap - Visual click tracking data

File Management

Upload File - Upload files for email attachments

Subscriptions & Billing

Get Plans - View available subscription plans
Create Subscription - Start a new subscription
Get Features - View enabled features
Manage Subscription - Access billing portal

Email Tracking

Open Tracking - Track email opens
Click Tracking - Track link clicks

SDKs & Libraries

Xem has two official SDKs:

Node.js and TypeScript: npm install @xem.email/sdk (example)
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
Support: Email us at team@xem.email
GitHub: Check our open source repositories

Changelog

Stay updated with our API changelog for the latest features, improvements, and breaking changes.

Ready to get started? Check out our quickstart guide or dive into the authentication docs.