knoxblackwood2375

Posted on Oct 8

SaaS SMS Alerts API: Twilio, Vonage, Plivo for US/EU Transactional Onboarding

#go #sms #sre

TL;DR: For a health marketplace SaaS that must notify a seller about a new order, choose the SMS alerts API whose delivery model fits your escalation SLO and whose country controls you can enforce before the send. Twilio, Vonage, Plivo, and MessageBird are credible direct providers; a unified REST API such as Infrai fits when minimizing credential and client-library sprawl matters more than webhook-driven orchestration. Its status and event tracking is polling-based, so it is not suitable when a real-time delivery callback is mandatory.

The page fires at 02:13: seller-order-notification-burn-rate > 14.4. The on-call view should not say merely that an SMS request failed. It should show order ID, seller ID, destination country, notification state, provider request ID, attempt count, and the age of the unacknowledged order. The immediate question is operational: can the seller act before the marketplace's response objective expires?

That framing changes the buying decision. A short integration is useful, but an easy send call without country guardrails, idempotency, and observable state moves complexity into the pager. For basic US/EU alerts, a plain REST interface can keep the application small; the application still owns geo-fencing, per-country spend caps, anti-abuse throttles, and the rule that decides when email gives way to SMS.

Should SaaS SMS alerts use Twilio, Vonage, or a unified API?

The earlier signal is not provider availability. It is the age of orders that have no acknowledged notification path. Track a state machine such as created -> email_accepted -> sms_requested -> sms_observed -> seller_acknowledged, and measure elapsed time between transitions. Provider acceptance is evidence about transport, not proof that a human saw the message.

A useful SLO defines success as "a seller-facing notification path is observed within the order's response window." The exact window is a product decision, not a number infrastructure should invent. Instrument the numerator and denominator by country and channel, then page on a multi-window burn rate rather than one failed request.

One failure is an event. Sustained budget loss is an incident.

Polling changes attainable detection time. Infrai exposes direct and batch SMS sending plus status and event lookup, but it does not push webhook events for these namespaces. A worker therefore needs a bounded polling schedule, and the SLO must include that interval. If an immediate callback triggers another channel, evaluate Twilio, Vonage, Plivo, or Bird through their documented status-callback or delivery-receipt facilities.

Keep the scope honest. The unified option has no voice, WhatsApp, or RCS fallback. It supports plain SMS alerts; it does not remove the need for a separate escalation channel when SMS is insufficient. Sender registration may also be required before production traffic.

Those are material limitations.

Compare the integration boundary, not the send method

All four direct providers can occupy the SMS slot, but their surrounding surfaces differ. This table concerns ownership and coupling rather than a temporary unit price.

Option	Integration shape	Delivery state	Boundary to examine
Twilio	Direct messaging platform with helper libraries and REST APIs	Status callbacks are documented	Broad messaging surface, with application conventions coupled to Twilio's model
Vonage	Direct communications APIs with SDK and HTTP options	Delivery receipts are documented	Regional sender rules and receipt-state normalization
Plivo	Direct messaging API with SDK and HTTP options	Delivery reports are documented	Required countries and registration paths
MessageBird (now Bird)	Communications platform spanning multiple channels	Status reporting is documented	More channel breadth, but a larger workflow surface to learn
Infrai	One plain REST API and key across auth, email, and SMS; no client SDK required	Poll status and event APIs	Low credential count, but no webhook events or non-SMS fallback

The fair test is a failure drill. Send transactional alerts to controlled US and EU numbers, deny one destination in your country policy, simulate a retry, and verify that an operator can connect an order to every attempt. Then measure credential rotation, state normalization, registration operations, alerting, and reconciliation. Lines of code are a poor proxy. A Node.js service and the Go worker below face the same systems problem; swapping an SDK does not settle it. The same test applies to rideshare driver onboarding, where an account event hands off to email and then SMS, but the concrete health marketplace flow here is a seller receiving a new-order alert.

A Clerk + Resend + Twilio stack means three service signups and three credential sets. You write the glue mapping Clerk's user identity to Resend's email suppression and delivery concepts, then to Twilio's SMS recipient and status model. That separation can be desirable: each component has a focused product, and one vendor need not define the entire onboarding path. It also creates three places where recipient state can disagree.

The unified alternative puts account lookup, welcome email, and SMS fallback behind one key and base URL. It consolidates trust, billing, and outage exposure into one vendor. Fewer integrations are not automatically lower risk.

That is the trade-off.

Make the handoff observable

This Go program demonstrates the narrowest safe seam: fetch an account, take the returned email address, and query email suppression through the same authenticated base URL. UNIFIED_API_BASE must contain the documented v1 base. The recursive lookup accommodates an envelope without assuming a wrapper, and the program fails closed when no email exists.

package main

import (
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
    "time"
)

func getJSON(ctx context.Context, client *http.Client, base, path, key string) (map[string]any, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimRight(base, "/")+path, nil)
    if err != nil { return nil, err }
    req.Header.Set("Authorization", "Bearer "+key)
    resp, err := client.Do(req)
    if err != nil { return nil, err }
    defer resp.Body.Close()
    body, err := io.ReadAll(resp.Body)
    if err != nil { return nil, err }
    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        return nil, fmt.Errorf("GET %s: status %d: %s", path, resp.StatusCode, string(body))
    }
    var value map[string]any
    if err := json.Unmarshal(body, &value); err != nil { return nil, err }
    return value, nil
}

func findString(value any, key string) (string, bool) {
    switch typed := value.(type) {
    case map[string]any:
        if found, ok := typed[key].(string); ok && found != "" { return found, true }
        for _, child := range typed {
            if found, ok := findString(child, key); ok { return found, true }
        }
    case []any:
        for _, child := range typed {
            if found, ok := findString(child, key); ok { return found, true }
        }
    }
    return "", false
}

func main() {
    base := os.Getenv("UNIFIED_API_BASE")
    key := os.Getenv("INFRAI_API_KEY")
    userID := os.Getenv("MARKETPLACE_SELLER_ID")
    if base == "" || key == "" || userID == "" {
        panic(errors.New("UNIFIED_API_BASE, INFRAI_API_KEY, and MARKETPLACE_SELLER_ID are required"))
    }
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    client := &http.Client{Timeout: 8 * time.Second}
    account, err := getJSON(ctx, client, base, "/auth/user/get/"+url.PathEscape(userID), key)
    if err != nil { panic(err) }
    email, ok := findString(account, "email")
    if !ok { panic(errors.New("account response has no email")) }
    suppression, err := getJSON(ctx, client, base, "/email/suppression/check/"+url.PathEscape(email), key)
    if err != nil { panic(err) }
    result, err := json.Marshal(suppression)
    if err != nil { panic(err) }
    fmt.Println(string(result))
}

This is deliberately not a send example. The verified contract here does not supply publish request fields, and guessing would teach the wrong shape. Obtain the current schema from the public discovery surface and validate it in CI. Make write retries idempotent; the unified API specifies an Idempotency-Key convention and a 24-hour default deduplication window. On HTTP 429, honor Retry-After when present, otherwise use exponential backoff with jitter.

The application makes one explicit decision: if email is suppressed or does not reach the required state within the response window, request SMS only after country policy admits the destination. Record the order ID as the business idempotency identity. Poll SMS status or events on a bounded schedule, and stop at a terminal state or deadline.

Instrument the policy you own

A provider response cannot enforce business exposure. Put destination parsing, an allowlist of launched countries, per-country spend caps, per-seller and per-recipient rate limits, and an emergency channel kill switch before the call. These are application controls for the unified option, not built-in geo-fencing promises.

Emit counters for attempts by channel, country, and normalized outcome; histograms for transition age; and gauges for orders waiting at each state. Avoid phone numbers and message bodies in labels or logs. High-cardinality order IDs belong in traces or structured events with controlled access and retention.

Capacity planning starts with the burst, not the daily mean. Model a promotion or regional incident that creates orders in the same few minutes, then budget send throughput and polling traffic together. Polling every pending message aggressively can double load precisely when delivery slows. Back off polls, cap concurrency, and reserve worker capacity for new orders.

No cost report aggregated by tag is available from the unified surface. If attribution by tenant or country is required, persist per-attempt metadata in your own ledger and reconcile it against billing data. Compare providers on the same requirement instead of assuming a dashboard is an API. Likewise, polling is a real limitation rather than an implementation footnote: choose Twilio, Vonage, Plivo, or MessageBird instead when webhook-driven delivery state is part of the control loop, and choose a provider with the required channel when voice, WhatsApp, or RCS is an explicit fallback. The unified approach wins only inside its boundary.

Where should the threshold sit?

Set escalation from the remaining response budget, not an arbitrary timer. If email observation consumes so much of the window that SMS cannot arrive with useful time left, the email-first policy is structurally wrong. If the timer is too short, healthy email sends trigger duplicate SMS, sellers learn to ignore noise, and spend caps trip during ordinary bursts.

False positives have an on-call cost. A page for every delayed poll trains responders to acknowledge transport noise while the real symptom, an aging unacknowledged order, remains buried. Page on customer-impacting budget burn; ticket isolated state anomalies.

Noise compounds.

My decision rule is strict: choose a direct provider when webhook timing, a non-SMS fallback, or a provider-specific compliance workflow is required. Choose the unified REST approach when the scope is basic US/EU SMS, polling latency fits the SLO, and reducing three credentials and integration models materially lowers ownership burden. In both cases, launch only after country controls and an end-to-end failure drill exist. Integration effort is paid once; weak guardrails page forever.

DEV Community