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/v1

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/v1/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 transactional-sdk
import { Transactional } from 'transactional-sdk';
 
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 transactional
from transactional 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="<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/v1/emails
SMSSMS messaging/v1/sms
FormsForm builder & submissions/v1/forms
SupportLive chat & conversations/v1/support
AuthAuthentication as a service/v1/auth
CalendarScheduling & bookings/v1/calendar
DomainsDomain registration & DNS/v1/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/v1/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/v1/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 current API version is v1. The version is included in the URL path:

https://api.usetransactional.com/v1/...

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