Skip to main content

​
Overview

The Usage Limits API allows you to check and manage email and SMS usage for customer subscriptions. All endpoints require SaaS Key authentication.

​
Authentication

All usage limit endpoints use the check.expiry middleware which requires a valid saas_key parameter.
See Authentication for details on SaaS Key authentication.

​
Common Parameters

All endpoints accept the following parameters:
​
saas_key
string
required
SaaS authentication key matching the environment variable SAAS_KEY
​
domain
string
required
Customer domain to check usage limits for. The domain is automatically normalized using trimDomain()

​
Email Limits

​
Get Total Email Limit

Retrieve the total email limit for a subscription. 
GET /api/user-emails-limit

curl -X GET "https://your-domain.com/api/user-emails-limit?saas_key=YOUR_SAAS_KEY&domain=customer-domain.com" \
  -H "Accept: application/json"
Response: 
1000
Returns the total number of emails included in the subscription package.

​
Check Email Limit Status

Verify if the email limit has been reached. 
GET /api/user-email-limit-check

curl -X GET "https://your-domain.com/api/user-email-limit-check?saas_key=YOUR_SAAS_KEY&domain=customer-domain.com" \
  -H "Accept: application/json"
Response: 
YES  // Can send emails
NO   // Limit reached

​
Get Remaining Email Limit

Get the number of emails remaining in the subscription. 
GET /api/user-email-limit-left

curl -X GET "https://your-domain.com/api/user-email-limit-left?saas_key=YOUR_SAAS_KEY&domain=customer-domain.com" \
  -H "Accept: application/json"
Response: 
450
Returns the number of emails remaining in the current subscription period.

​
Decrement Email Limit

Decrement the email count when an email is sent. 
POST /api/user-email-limit-decrement

curl -X POST "https://your-domain.com/api/user-email-limit-decrement" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "saas_key": "YOUR_SAAS_KEY",
    "domain": "customer-domain.com"
  }'
Response: 
true
Returns true if the decrement was successful.

​
SMS Limits

​
Get Total SMS Limit

Retrieve the total SMS limit for a subscription. 
GET /api/user-sms-limit

curl -X GET "https://your-domain.com/api/user-sms-limit?saas_key=YOUR_SAAS_KEY&domain=customer-domain.com" \
  -H "Accept: application/json"
Response: 
500
Returns the total number of SMS messages included in the subscription package.

​
Check SMS Limit Status

Verify if the SMS limit has been reached. 
GET /api/user-sms-limit-check

curl -X GET "https://your-domain.com/api/user-sms-limit-check?saas_key=YOUR_SAAS_KEY&domain=customer-domain.com" \
  -H "Accept: application/json"
Response: 
YES  // Can send SMS
NO   // Limit reached

​
Get Remaining SMS Limit

Get the number of SMS messages remaining in the subscription. 
GET /api/user-sms-limit-left

curl -X GET "https://your-domain.com/api/user-sms-limit-left?saas_key=YOUR_SAAS_KEY&domain=customer-domain.com" \
  -H "Accept: application/json"
Response: 
250
Returns the number of SMS messages remaining in the current subscription period.

​
Decrement SMS Limit

Decrement the SMS count when a message is sent. 
POST /api/user-sms-limit-decrement

curl -X POST "https://your-domain.com/api/user-sms-limit-decrement" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "saas_key": "YOUR_SAAS_KEY",
    "domain": "customer-domain.com"
  }'
Response: 
true
Returns true if the decrement was successful.

​
Error Responses

All endpoints return the same error format: 
{
  "error": "Unauthorized"
}
Status CodeDescription
200Success
401Unauthorized - Invalid or missing saas_key

​
Usage Workflow

​
Example Use Cases

​
Check Before Sending Email

<?php
function can_send_email($domain) {
    $response = wp_remote_get(
        'https://your-domain.com/api/user-email-limit-check?' . http_build_query([
            'saas_key' => env('SAAS_KEY'),
            'domain' => $domain
        ])
    );
    
    return wp_remote_retrieve_body($response) === 'YES';
}

function send_customer_email($domain, $recipient, $message) {
    if (!can_send_email($domain)) {
        return ['error' => 'Email limit reached'];
    }
    
    // Send email
    $sent = wp_mail($recipient, 'Subject', $message);
    
    if ($sent) {
        // Decrement the limit
        wp_remote_post('https://your-domain.com/api/user-email-limit-decrement', [
            'body' => json_encode([
                'saas_key' => env('SAAS_KEY'),
                'domain' => $domain
            ]),
            'headers' => ['Content-Type' => 'application/json']
        ]);
        
        return ['success' => 'Email sent'];
    }
    
    return ['error' => 'Failed to send email'];
}

​
Display Usage Statistics

async function getUsageStats(domain, saasKey) {
  const params = new URLSearchParams({ saas_key: saasKey, domain });
  const baseUrl = 'https://your-domain.com/api';
  
  // Fetch all stats in parallel
  const [emailLimit, emailLeft, smsLimit, smsLeft] = await Promise.all([
    fetch(`${baseUrl}/user-emails-limit?${params}`).then(r => r.json()),
    fetch(`${baseUrl}/user-email-limit-left?${params}`).then(r => r.json()),
    fetch(`${baseUrl}/user-sms-limit?${params}`).then(r => r.json()),
    fetch(`${baseUrl}/user-sms-limit-left?${params}`).then(r => r.json())
  ]);
  
  return {
    email: {
      total: emailLimit,
      remaining: emailLeft,
      used: emailLimit - emailLeft,
      percentage: ((emailLimit - emailLeft) / emailLimit * 100).toFixed(1)
    },
    sms: {
      total: smsLimit,
      remaining: smsLeft,
      used: smsLimit - smsLeft,
      percentage: ((smsLimit - smsLeft) / smsLimit * 100).toFixed(1)
    }
  };
}

// Usage
const stats = await getUsageStats('customer-domain.com', 'YOUR_SAAS_KEY');
console.log(`Email usage: ${stats.email.used}/${stats.email.total} (${stats.email.percentage}%)`);
console.log(`SMS usage: ${stats.sms.used}/${stats.sms.total} (${stats.sms.percentage}%)`);

​
Rate Limiting Middleware

from functools import wraps
import requests

def check_email_limit(func):
    """Decorator to check email limit before executing function"""
    @wraps(func)
    def wrapper(domain, *args, **kwargs):
        response = requests.get(
            'https://your-domain.com/api/user-email-limit-check',
            params={
                'saas_key': 'YOUR_SAAS_KEY',
                'domain': domain
            }
        )
        
        if response.text == 'YES':
            result = func(domain, *args, **kwargs)
            
            # Decrement after successful send
            requests.post(
                'https://your-domain.com/api/user-email-limit-decrement',
                json={'saas_key': 'YOUR_SAAS_KEY', 'domain': domain}
            )
            
            return result
        else:
            raise Exception('Email limit reached')
    
    return wrapper

@check_email_limit
def send_notification_email(domain, recipient, message):
    # Your email sending logic
    print(f"Sending email to {recipient}")
    return True

# Usage
try:
    send_notification_email('customer-domain.com', '[email protected]', 'Hello!')
    print("Email sent successfully")
except Exception as e:
    print(f"Error: {e}")

​
Notes

Always check the limit status before sending emails or SMS. Decrement the count only after successful delivery.
  • Domains are automatically normalized using trimDomain()
  • Usage counts are tracked in the item_limit_count table
  • Limits reset based on the subscription period
  • Helper functions abstract the implementation details

Check Expiry

Verify subscription status

Authentication

Learn about SaaS Key authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us