Usage & Analytics

Every senderZ plan includes unlimited messages to existing contacts. What is metered is new contacts — unique phone numbers your tenant has never messaged before. The Usage API gives you real-time visibility into how many new contacts you have used this billing period, what your plan limits are, and when your period resets.

Checking Your Usage

Example Request

curl https://api.senderz.com/v1/billing/usage \
  -H "Authorization: Bearer sz_live_YOUR_KEY"

{
  "data": {
    "plan": "growth",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "new_contacts": {
      "used_today": 12,
      "limit_today": 50,
      "used_this_month": 487,
      "limit_this_month": 1250
    },
    "messages": {
      "sent": 3842,
      "delivered": 3790,
      "failed": 52,
      "blocked": 14
    },
    "channels": {
      "imessage": 3201,
      "sms": 641
    }
  }
}

Response Fields

Plan Limits Reference

All plans include unlimited messages to contacts you have already messaged. There are no per-message fees and no overage charges. When you hit your new contact limit, messages to new numbers are queued until the next day (daily limit) or next billing period (monthly limit).

Understanding the Period Format

The period_start and period_end fields align with your Stripe billing cycle. If you subscribed on April 10, your period runs from the 10th of each month to the 9th of the next. All timestamps are in UTC.

Daily limits reset at midnight UTC. Monthly limits reset at period_start.

Monitoring Usage Programmatically

If you want to display usage in your own dashboard or trigger alerts when you are approaching your limit, poll GET /v1/billing/usage periodically. A reasonable polling interval is every 5 to 15 minutes during business hours.

const res = await fetch('https://api.senderz.com/v1/billing/usage', {
  headers: { 'Authorization': 'Bearer sz_live_YOUR_KEY' },
})
const { data } = await res.json()

const monthlyPct = (data.new_contacts.used_this_month / data.new_contacts.limit_this_month) * 100
if (monthlyPct >= 80) {
  console.warn(`Usage alert: ${monthlyPct.toFixed(0)}% of monthly new contacts used`)
}

Webhook Delivery Logs

For debugging delivery issues, you can review webhook delivery attempts through GET /v1/webhooks to list your registered webhooks, and then check the delivery logs in the developer portal under Webhooks > Delivery Log. Each log entry shows:

• The event type that triggered the webhook
• The HTTP status code returned by your server
• The number of delivery attempts (senderZ retries failed webhooks up to 3 times)
• The timestamp of each attempt

This is useful for diagnosing why your webhook handler might be missing events — common causes include returning a non-2xx status code, taking longer than 10 seconds to respond, or having an expired SSL certificate.

Message Status Breakdown

When reviewing your usage, understanding message statuses helps you identify issues:

A healthy account typically sees a delivered rate above 95%. If your failure rate is climbing, check whether you are sending to landlines (which cannot receive iMessage or SMS) or to numbers that have been disconnected.

Analytics Retention by Plan

Your message and usage data is retained based on your plan:

After the retention window, aggregate counts remain available but individual message details are purged. If you need long-term records, export your data regularly via the API or developer portal.