API Keys

What are API Keys?

API keys are credentials that authenticate your application when making API requests to send emails. Each key is scoped to a specific email server.

Key Types

Full Access Keys

Full access keys can:

• Send emails
• Manage server settings
• Create and manage streams
• View analytics and logs
• Manage suppression lists

Use for: Admin dashboards, backend services with full control

Send-Only Keys

Send-only keys can:

• Send emails
• View basic delivery status

Cannot:

• Modify server settings
• View detailed analytics
• Manage suppressions

Use for: Frontend applications, microservices, third-party integrations

Creating API Keys

Via Dashboard

1. Go to Email > Servers > [Your Server] > API Keys
2. Click Create API Key
3. Configure the key:
   • Name - Descriptive name (e.g., "Production Backend")
   • Type - Full Access or Send Only
4. Click Create
5. Copy the key immediately - it won't be shown again

Via API

const key = await client.apiKeys.create({
  serverId: 'srv_123',
  name: 'Production Backend',
  type: 'full_access',
});
 
console.log(key.key); // Copy this!

Using API Keys

HTTP Header Authentication

Include the API key in the Authorization header:

curl -X POST https://api.usetransactional.com/v1/emails/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

SDK Configuration

import { Transactional } from 'transactional-sdk';
 
const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});

Environment Variables

Store API keys in environment variables, never in code:

# .env
TRANSACTIONAL_API_KEY=txk_live_abc123...

// config.ts
export const transactionalKey = process.env.TRANSACTIONAL_API_KEY;

Key Prefixes

API keys have prefixes indicating their type:

Security Best Practices

Never Expose Keys Client-Side

API keys should never be:

• Included in frontend JavaScript
• Committed to version control
• Shared in logs or error messages
• Sent to third parties

Use Environment Variables

# Development
export TRANSACTIONAL_API_KEY=txk_test_...
 
# Production (set in your deployment platform)
TRANSACTIONAL_API_KEY=txk_live_...

Rotate Keys Regularly

Create new keys and retire old ones periodically:

1. Create a new key
2. Update your application to use the new key
3. Verify the new key works
4. Delete the old key

Minimum Permissions

Use send-only keys when full access isn't needed:

• Microservices that only send emails
• Third-party integrations
• Client applications

Monitor Key Usage

Review API key usage in your dashboard:

• Which keys are being used
• Request patterns and volumes
• Failed authentication attempts

Revoking Keys

If a key is compromised:

1. Go to API Keys in your server
2. Find the compromised key
3. Click Revoke or Delete
4. Create a new key
5. Update your application

Revoked keys stop working immediately.

Key Limits

Troubleshooting

Invalid API Key Error

• Verify the key is copied correctly
• Check for extra whitespace
• Ensure the key hasn't been revoked
• Confirm you're using the right server's key

Permission Denied Error

• Check if using a send-only key for admin operations
• Verify the key has the required permissions

Next Steps

• Quick Start - Send your first email
• Best Practices - Security recommendations
• API Reference - Complete API documentation