SDK examples

// GatorSMS.js — tiny helper library
const BASE = "https://gatorsms.com/api/v1";

class GatorSMSClient {
  constructor(apiKey) { this.apiKey = apiKey; }

  async _req(method, path, body) {
    const res = await fetch(`${BASE}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    const json = await res.json();
    if (!json.success) {
      const e = json.error;
      throw new Error(`[${e.code}] ${e.message}`);
    }
    return json.data;
  }

  send(params)        { return this._req("POST", "/messages/send", params); }
  bulk(params)        { return this._req("POST", "/messages/bulk", params); }
  get(id)             { return this._req("GET",  `/messages/${id}`); }
  list(filters = {})  {
    const qs = new URLSearchParams(filters).toString();
    return this._req("GET", `/messages${qs ? `?${qs}` : ""}`);
  }
  balance()           { return this._req("GET",  "/balance"); }
}

// Usage:
const GatorSMS = new GatorSMSClient(process.env.GatorSMS_API_KEY);
const msg = await GatorSMS.send({
  to: "+12025550143",
  from: "GatorSMS",
  body: "Hi from GatorSMS!",
});
console.log(msg.id, msg.status);

# GatorSMS.py — tiny helper library
import os, requests

class GatorSMSClientError(Exception): ...

class GatorSMSClient:
    BASE = "https://gatorsms.com/api/v1"

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        })

    def _req(self, method, path, **kwargs):
        r = self.session.request(method, f"{self.BASE}{path}", timeout=15, **kwargs)
        body = r.json()
        if not body.get("success"):
            e = body["error"]
            raise GatorSMSError(f"[{e['code']}] {e['message']}")
        return body["data"]

    def send(self, **kwargs):     return self._req("POST", "/messages/send", json=kwargs)
    def bulk(self, **kwargs):     return self._req("POST", "/messages/bulk", json=kwargs)
    def get(self, message_id):    return self._req("GET",  f"/messages/{message_id}")
    def list(self, **filters):    return self._req("GET",  "/messages", params=filters)
    def balance(self):            return self._req("GET",  "/balance")


# Usage:
GatorSMS = GatorSMSClient(os.environ["GatorSMS_API_KEY"])
msg = GatorSMS.send(to="+12025550143", from_="GatorSMS", body="Hi from GatorSMS!")
print(msg["id"], msg["status"])

curl https://gatorsms.com/api/v1/messages/send \
  -H "Authorization: Bearer $GatorSMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to":   "+12025550143",
    "from": "GatorSMS",
    "body": "Hi from GatorSMS!"
  }'

const message = await GatorSMS.get(messageId);

switch (message.status) {
  case "pending":   /* not yet sent */         break;
  case "sent":      /* accepted by provider */ break;
  case "delivered": /* confirmed by carrier */ break;
  case "failed":
    console.error("Failed:", message.error?.message);
    break;
}

message = GatorSMS.get(message_id)

if message["status"] == "failed":
    print("Failed:", message["error"]["message"])
elif message["status"] == "delivered":
    print("Delivered at:", message["delivered_at"])

curl https://gatorsms.com/api/v1/messages/msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc \
  -H "Authorization: Bearer $GatorSMS_API_KEY"

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/GatorSMS",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const header = req.header("GatorSMS-Signature");
    const [t, v1] = header.split(",").map(s => s.split("=")[1]);

    const expected = crypto
      .createHmac("sha256", process.env.GatorSMS_WEBHOOK_SECRET)
      .update(`${t}.${req.body.toString()}`)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
      return res.status(400).send("invalid signature");
    }

    const event = JSON.parse(req.body.toString());
    // Always ack quickly. Do the real work in a queue.
    queue.publish("GatorSMS.events", event);
    res.sendStatus(200);
  }
);

app.listen(3000);

import os, hmac, hashlib, json
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["GatorSMS_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/GatorSMS")
def GatorSMS_webhook():
    raw = request.get_data()
    header = request.headers.get("GatorSMS-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(
        SECRET,
        f"{parts['t']}.{raw.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, parts["v1"]):
        abort(400, "invalid signature")

    event = json.loads(raw)
    # Enqueue and return 200 fast.
    queue.publish("GatorSMS.events", event)
    return "", 200