Quickstart

Apian Labs Relay lets you validate deterministic routing and proof artifacts in test mode before sending production traffic. This quickstart walks through workspace setup, sending a message, and verifying a signed webhook in about 10 minutes.

1. Create a workspace and API key

Create a workspace in the dashboard, then generate an API key for server-side use. Keep the key in a secure secret store and use it from backend services only.

2. Connect providers (Twilio and Telnyx)

Connect at least two providers so Apian Labs Relay can apply deterministic failover. You can start with one provider in test mode, but failover requires two.

3. Send a test message

Use the API key in the x-api-key header and send a message to an allowlisted test destination.

curl -X POST https://api.apianlabs.com/v1/messages \
  -H "x-api-key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "from": "+14155559876",
    "body": "Relay test: payment received.",
    "segment": "transactional",
    "metadata": {
      "orderId": "ord_1234"
    }
  }'

Node SDK example:

npm install apian-relay

import { Relay } from "apian-relay";

const relay = new Relay({ apiKey: process.env.RELAY_API_KEY! });

const response = await relay.sendMessage({
  to: "+14155551234",
  from: "+14155559876",
  body: "Relay test: payment received.",
  segment: "transactional",
  metadata: { orderId: "ord_1234" }
});

console.log("Message ID:", response.messageId);

4. Fetch message status

Retrieve the latest delivery status for the message.

curl -X GET https://api.apianlabs.com/v1/messages/{messageId} \
  -H "x-api-key: $RELAY_API_KEY"

const status = await relay.getMessageStatus(response.messageId);
console.log(status.status);

5. Fetch the trace timeline

Pull the trace to see provider attempts, receipts, and failover decisions.

curl -X GET https://api.apianlabs.com/v1/messages/{messageId}/trace \
  -H "x-api-key: $RELAY_API_KEY"

const trace = await relay.getTrace(response.messageId);
console.log(trace.attempts.length);

6. Configure a webhook and verify the signature

Create a webhook endpoint in the dashboard, then add the secret to your server environment. Apian Labs Relay signs each payload using the x-apian-timestamp and x-apian-signature headers.

import { verifyWebhookSignature } from "apian-relay";

const rawBody = await getRawBody(req);
const isValid = verifyWebhookSignature(
  rawBody,
  req.headers,
  process.env.RELAY_WEBHOOK_SECRET!
);

if (!isValid) {
  res.status(401).send("Invalid signature");
  return;
}

res.status(200).send("ok");

Next steps

Concepts