Transactional

Quick Start

Send your first SMS message in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

  1. A Transactional account (sign up free)
  2. SMS enabled for your organization
  3. An API key from your dashboard

Step 1: Enable SMS

SMS must be enabled for your organization:

  1. Go to your Dashboard
  2. Navigate to SMS in the sidebar
  3. If not enabled, request access and complete onboarding

Step 2: Browse Available Templates

Templates are pre-approved by carriers for reliable delivery:

  1. Go to SMS > Templates
  2. Browse the Pool Templates tab
  3. Find templates that match your use case (OTP, alerts, etc.)
  4. Click Add to Organization on templates you need

Step 3: Configure Your Template

After adding a template:

  1. Go to the My Templates tab
  2. Optionally set a custom alias (e.g., my-otp-template)
  3. Note the template variables (e.g., {{code}}, {{name}})

Step 4: Get Your API Key

  1. Go to Email > Servers (API keys are shared with email)
  2. Select your server or create one
  3. Go to API Keys tab
  4. Create a new API key and copy it securely

Step 5: Send Your First SMS

Using the TypeScript SDK

Install the SDK:

npm install transactional-sdk

Send an SMS:

import { Transactional } from 'transactional-sdk';
 
const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
async function sendVerificationCode() {
  const result = await client.sms.send({
    to: '+14155551234',
    templateAlias: 'otp-verification',
    templateModel: {
      code: '123456',
    },
  });
 
  console.log('SMS sent:', result.messageId);
}
 
sendVerificationCode();

Using the Python SDK

Install the SDK:

pip install transactional

Send an SMS:

from transactional import Transactional
import os
 
client = Transactional(api_key=os.environ["TRANSACTIONAL_API_KEY"])
 
result = client.sms.send(
    to="+14155551234",
    template_alias="otp-verification",
    template_model={
        "code": "123456",
    },
)
 
print(f"SMS sent: {result.message_id}")

Using cURL

curl -X POST https://api.usetransactional.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "templateAlias": "otp-verification",
    "templateModel": {
      "code": "123456"
    }
  }'

Response

{
  "to": "+14155551234",
  "submittedAt": "2024-01-01T00:00:00.000Z",
  "messageId": "sms_abc123",
  "errorCode": 0,
  "message": "OK"
}

Step 6: Check Delivery Status

You can check the status of your message:

Using the TypeScript SDK

const message = await client.sms.get('sms_abc123');
console.log('Status:', message.status);
// QUEUED, SENT, DELIVERED, FAILED

Using the Python SDK

message = client.sms.get("sms_abc123")
print(f"Status: {message.status}")
# QUEUED, SENT, DELIVERED, FAILED

Using cURL

curl https://api.usetransactional.com/v1/sms/sms_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "messageId": "sms_abc123",
  "from": "+18005551234",
  "to": "+14155551234",
  "body": "Your verification code is 123456",
  "status": "DELIVERED",
  "direction": "OUTBOUND",
  "segments": 1,
  "country": "US",
  "queuedAt": "2024-01-01T00:00:00.000Z",
  "sentAt": "2024-01-01T00:00:01.000Z",
  "deliveredAt": "2024-01-01T00:00:02.000Z"
}

Understanding Message Status

StatusDescription
QUEUEDMessage accepted and queued for delivery
SENDINGMessage is being sent to carrier
SENTMessage sent to carrier
DELIVEREDMessage delivered to recipient
FAILEDDelivery failed (check errorMessage)
UNDELIVEREDCarrier unable to deliver

What's Next?

Now that you've sent your first SMS, explore more features: