Transactional

API Overview

Overview of the Transactional REST API.

API Overview

The Transactional API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

All API requests should be made to:

https://api.usetransactional.com

Authentication

The Transactional API uses API keys to authenticate requests. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Or use the X-API-Key header:

X-API-Key: YOUR_API_KEY

See Authentication for detailed information.

Request Format

All requests should include the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://api.usetransactional.com/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "subject": "Hello!",
    "html": "<h1>Hello World</h1>"
  }'

Response Format

All responses are returned in JSON format:

Success Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123",
    "status": "QUEUED"
  }
}

List Response

{
  "success": true,
  "data": [...],
  "meta": {
    "count": 20,
    "offset": 0,
    "total": 150,
    "hasMore": true
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid."
  }
}

See Error Handling for detailed error codes.

SDK Quickstart

TypeScript SDK

npm install @usetransactional/node
import { Transactional } from '@usetransactional/node';
 
const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
// Send an email
const email = await client.emails.send({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Hello!',
  html: '<h1>Hello World</h1>',
});
 
console.log(`Email sent: ${email.messageId}`);
 
// Send an SMS
const sms = await client.sms.send({
  to: '+14155551234',
  templateAlias: 'otp-verification',
  templateModel: { code: '123456' },
});
 
console.log(`SMS sent: ${sms.messageId}`);

Python SDK

pip install usetransactional
from usetransactional import Transactional
import os
 
client = Transactional(api_key=os.environ["TRANSACTIONAL_API_KEY"])
 
# Send an email
email = client.emails.send(
    from_email="sender@example.com",
    to="recipient@example.com",
    subject="Hello!",
    html_body="<h1>Hello World</h1>",
)
 
print(f"Email sent: {email.message_id}")
 
# Send an SMS
sms = client.sms.send(
    to="+14155551234",
    template_alias="otp-verification",
    template_model={"code": "123456"},
)
 
print(f"SMS sent: {sms.message_id}")

API Modules

The API is organized into modules:

ModuleDescriptionBase Path
EmailTransactional email sending/emails
SMSSMS messaging/sms
FormsForm builder & submissions/forms
SupportLive chat & conversations/support
AuthAuthentication as a service/auth
CalendarScheduling & bookings/calendar
DomainsDomain registration & DNS/domains

Rate Limits

The API is rate limited to ensure fair usage. The current limits are:

PlanRequests per second
Starter50
Growth200
Scale1,000
EnterpriseCustom

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

See Rate Limiting for detailed information.

Pagination

List endpoints support pagination:

curl "https://api.usetransactional.com/emails/messages?count=50&offset=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Pagination for detailed information.

Webhooks

Receive real-time notifications when events occur:

curl -X POST https://api.usetransactional.com/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["email.delivered", "email.bounced"]
  }'

See Webhooks for detailed information.

API Versioning

The API does not use version prefixes in the URL path. All endpoints are accessed directly at the base URL.

We follow semantic versioning and will notify you of any breaking changes in advance.

Support

Need help? Here's how to get support:

When contacting support, please include:

  • Your organization ID
  • The API endpoint you're calling
  • The request ID from the X-Request-Id header
  • The full error response

Next Steps