API Reference — Authentication & Send API

The XSender API exposes a small, focused HTTP surface for sending Email, SMS, and WhatsApp messages from any external system: backends, CRMs, mobile apps, no-code platforms, e-commerce stores, and automation tools such as Zapier or Make.

This page is the canonical reference for: authentication, base URL, headers, request and response format, rate limits, errors, and the /api/email/send, /api/sms/send, /api/whatsapp/send endpoints.

Base URL

Every request is made against the installation's own domain:

https://YOUR-XSENDER-DOMAIN/api

Replace YOUR-XSENDER-DOMAIN with the host where you installed XSender (for example app.example.com). All examples below use a placeholder.

Authentication

Every request must include your API key in the request header:

Where to find your API key

• User panel: User Panel → Settings → API Key. Each user has their own key tied to their account, gateways, contacts, and plan limits.
• Admin panel: Admin Panel → Settings → API Key. Admin-scope key uses the admin's configured gateways and bypasses user plan checks.

Security: treat the API key like a password. Rotate it whenever you suspect compromise. Use TLS (HTTPS) for every request — XSender refuses plain-HTTP API traffic by default.

Response format

All endpoints return JSON with a consistent envelope:

{
  "success": true,
  "message": "Human readable status",
  "data":    [ /* per-endpoint payload */ ]
}

On failure, success is false and an appropriate HTTP status code is returned. See Errors below.

Send Email — POST /api/email/send

Sends one or many emails through the gateway you select via gateway_identifier, or — if omitted — the user's default email gateway.

Single recipient

{
  "contact": [
    {
      "email":              "[email protected]",
      "subject":            "Welcome to Acme",
      "message":            "Hi Alice,\nThanks for signing up.",
      "sender_name":        "Acme Support",
      "gateway_identifier": "smtp-primary"
    }
  ]
}

Bulk (up to thousands per request)

{
  "contact": [
    { "email": "[email protected]", "subject": "Hi Alice", "message": "..." },
    { "email": "[email protected]",   "subject": "Hi Bob",   "message": "..." },
    { "email": "[email protected]", "subject": "Hi Carol", "message": "..." }
  ]
}

Scheduled send

{
  "contact": [
    {
      "email":       "[email protected]",
      "subject":     "Reminder",
      "message":     "Don't forget…",
      "schedule_at": "2026-06-01 09:00:00"
    }
  ]
}

schedule_at must be in Y-m-d H:i:s format in the XSender server's timezone.

Attachments

{
  "contact": [
    {
      "email":   "[email protected]",
      "subject": "Your invoice",
      "message": "Please find your invoice attached.",
      "attachments": [
        { "type": "image", "url": "https://cdn.example.com/img/logo.png" },
        { "type": "file",  "url": "https://cdn.example.com/inv/2026-05.pdf" }
      ]
    }
  ]
}

cURL example

curl -X POST https://YOUR-XSENDER-DOMAIN/api/email/send \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": [
      { "email": "[email protected]", "subject": "Hello", "message": "Hi from XSender" }
    ]
  }'

Response

{
  "success": true,
  "message": "New Email Request Sent, Please Check The Email History For Final Status",
  "data": [
    {
      "uid":        "c8d1b339-1887-45bb-aee4-8cdc3e98e0a1",
      "email":      "[email protected]",
      "status":     "Pending",
      "created_at": "2026-05-23 12:00 PM"
    }
  ]
}

Each uid can be used later with GET /api/get/email/{uid} to fetch the final delivery state (Sent, Delivered, Opened, Bounced, Failed, etc.).

Send SMS — POST /api/sms/send

{
  "contact": [
    {
      "number":             "+15555550123",
      "body":               "Your verification code is 482915",
      "sms_type":           "plain",
      "gateway_identifier": "twilio-primary"
    }
  ]
}

sms_type is one of plain, otp, marketing. gateway_identifier picks a specific SMS gateway; omit it to use the user's default. Scheduling, bulk, and response shape mirror the Email endpoint.

Send WhatsApp — POST /api/whatsapp/send

{
  "contact": [
    {
      "number":       "+15555550123",
      "message":      "Your order *#A1023* has shipped.",
      "session_name": "store-main"
    }
  ]
}

Media message

{
  "contact": [
    {
      "number":       "+15555550123",
      "message":      "Order confirmation",
      "media":        "image",
      "url":          "https://cdn.example.com/orders/A1023.png",
      "session_name": "store-main"
    }
  ]
}

session_name targets a specific connected WhatsApp session (Node device or WhatsApp Cloud API gateway). Omit it to use the user's primary session. Supported media values: image, video, audio, document.

Query-string send (legacy / quick-test)

For simple integrations (such as some IoT devices), each send endpoint also accepts GET:

GET /api/email/[email protected]&subject=Hi&message=Hello
GET /api/sms/send?number=+15555550123&body=Code+482915
GET /api/whatsapp/send?number=+15555550123&message=Hello

Same Api-key header is required. Do not place the API key in the query string.

Fetch delivery status — GET /api/get/{channel}/{uid}

GET /api/get/email/c8d1b339-1887-45bb-aee4-8cdc3e98e0a1
GET /api/get/sms/aa1bd670-861f-4607-9695-2710cffa1234
GET /api/get/whatsapp/1ea910b9-bafb-41b1-82a5-bb8c750e5678

Returns the dispatch record with current status, gateway response, timestamps, and (for email) tracking events.

Rate limits

Default: 60 requests / minute / API key against the api middleware. Webhook endpoints are exempt from this throttle. Bulk sends count as one API request regardless of recipient count, so prefer batching to many small calls.

When throttled, XSender returns HTTP 429 with header Retry-After indicating seconds until you may retry.

Errors

Next steps

• Build an automation that listens for events: Webhooks — Incoming Triggers
• Capture email opens, clicks, bounces from your ESP: Email Delivery Webhooks
• Connect a phone as a sending device: Android SMS Gateway API
• Understand admin-vs-user scope: Administrative API & Permissions