Rackspace Email Setup & Configuration

This guide covers the setup and configuration of the Rackspace Email integration for the MyNATCA Platform.

Prerequisites

Rackspace Email Account

Active Rackspace Email account with API access
API credentials (API Key and Secret Key)
Customer Account Number
Admin access to Rackspace Email Admin Panel

Platform Requirements

MyNATCA Platform deployed and running
Auth0 authentication configured
MySQL database access
Supabase connection configured

Rackspace API Configuration

Obtaining API Credentials

Login to Rackspace Email Admin Panel
- Navigate to https://admin.emailsrvr.com (opens in a new tab)
- Login with your admin credentials
Generate API Key
- Go to My Account > API Keys
- Click Generate New API Key
- Copy and save the API Key securely
- Copy and save the Secret Key securely
- Note: Secret Key is only shown once - save it immediately
Get Customer Account Number
- Found in My Account > Account Settings
- Displayed as "Account Number" or "Customer ID"
- Format: Usually 6-8 digit number

API Authentication Method

The Rackspace Email API uses a custom authentication scheme with the following components:

X-Api-Signature Header

All API requests require an X-Api-Signature header calculated as:

const crypto = require('crypto');
 
// Components
const apiKey = 'your_api_key';
const secretKey = 'your_secret_key';
const userAgent = 'MyNATCA Platform';
const timestamp = Math.floor(Date.now() / 1000).toString();
 
// Calculate signature
const dataToSign = apiKey + userAgent + timestamp + secretKey;
const signature = crypto.createHash('sha1').update(dataToSign).digest('hex');
 
// Request headers
const headers = {
  'X-Api-Signature': `${apiKey}:${timestamp}:${signature}`,
  'User-Agent': userAgent,
  'Content-Type': 'application/json'
};

Signature Components

API Key: Your Rackspace API key
Timestamp: Current Unix timestamp (seconds since epoch)
User Agent: Fixed string 'MyNATCA Platform'
Secret Key: Your Rackspace secret key (never sent in request)

Signature Calculation

dataToSign = apiKey + userAgent + timestamp + secretKey
signature = SHA1(dataToSign)
headerValue = apiKey + ':' + timestamp + ':' + signature

API Endpoints

The Rackspace Email API base URL:

https://api.emailsrvr.com/v1

Environment Variables Setup

Required Variables

Add the following environment variables to your Platform deployment:

# Rackspace Email API Credentials
RACKSPACE_API_KEY=your_api_key_here
RACKSPACE_SECRET_KEY=your_secret_key_here
RACKSPACE_CUSTOMER_ID=123456
 
# Example values (DO NOT USE IN PRODUCTION)
# RACKSPACE_API_KEY=abc123def456ghi789
# RACKSPACE_SECRET_KEY=xyz789abc123def456ghi789jkl012
# RACKSPACE_CUSTOMER_ID=654321

Digital Ocean App Platform

Via Web Console

Navigate to your Platform app in Digital Ocean
Go to Settings > App-Level Environment Variables
Add each variable:
- RACKSPACE_API_KEY = (your API key)
- RACKSPACE_SECRET_KEY = (your secret key)
- RACKSPACE_CUSTOMER_ID = (your customer ID)
Mark as Secret for sensitive values
Save and redeploy

Via CLI

doctl apps update $APP_ID --env RACKSPACE_API_KEY="your_api_key"
doctl apps update $APP_ID --env RACKSPACE_SECRET_KEY="your_secret_key"
doctl apps update $APP_ID --env RACKSPACE_CUSTOMER_ID="123456"

Local Development

Add to .env file in Platform root:

# .env (local development)
RACKSPACE_API_KEY=your_api_key_here
RACKSPACE_SECRET_KEY=your_secret_key_here
RACKSPACE_CUSTOMER_ID=123456

Important: Never commit .env file to version control. Ensure it's in .gitignore.

Vercel Deployment

# Add environment variables to Vercel
vercel env add RACKSPACE_API_KEY production
vercel env add RACKSPACE_SECRET_KEY production
vercel env add RACKSPACE_CUSTOMER_ID production

Platform Configuration

Database Schema

The Rackspace integration uses the existing emailinformation table in MySQL to store created email addresses:

-- Email information table (existing schema)
CREATE TABLE emailinformation (
  emailinformationid INT PRIMARY KEY AUTO_INCREMENT,
  membernumber VARCHAR(20),
  emailaddress VARCHAR(255),
  emailtypeid INT,
  isactive BOOLEAN DEFAULT 1,
  createddate DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_membernumber (membernumber),
  INDEX idx_emailaddress (emailaddress)
);

No additional database changes are required for the Rackspace integration.

Email Type Configuration

NATCA.net emails should use a specific email type ID to distinguish them from personal emails:

// Suggested email type ID for NATCA.net emails
const NATCA_EMAIL_TYPE_ID = 3; // Organizational email
 
// When creating email in database:
await pool.query(
  'INSERT INTO emailinformation (membernumber, emailaddress, emailtypeid) VALUES (?, ?, ?)',
  [memberNumber, email, NATCA_EMAIL_TYPE_ID]
);

API Route Configuration

The Rackspace routes are automatically mounted in the Platform server:

// server.js
const rackspaceRoutes = require('./routes/rackspace');
 
// Mount Rackspace routes
app.use('/api/rackspace', rackspaceRoutes);

Endpoints available:

POST /api/rackspace/check-availability
POST /api/rackspace/create-email
POST /api/rackspace/reset-password

Client Library Configuration

The Rackspace API client is located at /sync/rackspace/lib/client.js and provides:

Methods

const RackspaceClient = require('./sync/rackspace/lib/client');
 
const client = new RackspaceClient({
  apiKey: process.env.RACKSPACE_API_KEY,
  secretKey: process.env.RACKSPACE_SECRET_KEY,
  customerId: process.env.RACKSPACE_CUSTOMER_ID
});
 
// Check if mailbox exists
const exists = await client.checkMailboxExists('jdoss@natca.net');
 
// Create new mailbox
const result = await client.createMailbox({
  emailAddress: 'jdoss@natca.net',
  password: 'SecureP@ss123',
  displayName: 'Jason Doss',
  firstName: 'Jason',
  lastName: 'Doss'
});
 
// Reset password
const reset = await client.resetPassword('jdoss@natca.net', 'NewP@ss456');
 
// Generate secure password
const password = client.generatePassword(); // Returns 16-char secure password

Password Requirements

The password generator creates passwords meeting Rackspace requirements:

Minimum Length: 8 characters
Character Types: At least 3 of the following:
- Uppercase letters (A-Z)
- Lowercase letters (a-z)
- Numbers (0-9)
- Special characters (!@#$%^&*)

The default generator creates 16-character passwords with all four character types for maximum security.

Email Format Generation

The client includes email format generation logic:

// Generate email format options
function generateEmailFormats(firstName, lastName) {
  const formats = [];
 
  // Format 1: first initial + last name (jdoss@natca.net)
  const format1 = `${firstName.charAt(0).toLowerCase()}${lastName.toLowerCase()}@natca.net`;
  formats.push(format1);
 
  // Format 2: firstname.lastname (jason.doss@natca.net)
  const format2 = `${firstName.toLowerCase()}.${lastName.toLowerCase()}@natca.net`;
  formats.push(format2);
 
  return formats;
}

Rate Limiting

The client includes automatic rate limiting:

// Built-in rate limiting (configured in client)
const client = new RackspaceClient({
  apiKey: process.env.RACKSPACE_API_KEY,
  secretKey: process.env.RACKSPACE_SECRET_KEY,
  customerId: process.env.RACKSPACE_CUSTOMER_ID,
  maxRetries: 3,
  retryDelay: 1000 // ms between retries
});

Testing Configuration

Test API Connection

Create a test script to verify Rackspace API connectivity:

// test-rackspace.js
const RackspaceClient = require('./sync/rackspace/lib/client');
 
async function testConnection() {
  const client = new RackspaceClient({
    apiKey: process.env.RACKSPACE_API_KEY,
    secretKey: process.env.RACKSPACE_SECRET_KEY,
    customerId: process.env.RACKSPACE_CUSTOMER_ID
  });
 
  try {
    // Test with a mailbox that shouldn't exist
    const exists = await client.checkMailboxExists('test99999@natca.net');
    console.log('✅ Rackspace API connection successful');
    console.log('Test mailbox exists:', exists);
  } catch (error) {
    console.error('❌ Rackspace API connection failed:', error.message);
  }
}
 
testConnection();

Run the test:

node test-rackspace.js

Expected Responses

Successful Connection

✅ Rackspace API connection successful
Test mailbox exists: false

Failed Connection

❌ Rackspace API connection failed: Invalid API credentials

Test Availability Check

# Test availability check endpoint
curl -X POST http://localhost:1300/api/rackspace/check-availability \
  -H "Content-Type: application/json" \
  -H "Cookie: platform.session=your_session_cookie" \
  -d '{"memberNumber": "12345"}'

Expected response:

{
  "memberNumber": "12345",
  "firstName": "Jason",
  "lastName": "Doss",
  "availableFormats": [
    "jdoss@natca.net",
    "jason.doss@natca.net"
  ]
}

Swagger Documentation

The Rackspace endpoints are documented in the Platform's Swagger documentation:

Update swagger.js

Ensure the Rackspace routes are included in the Swagger configuration:

// swagger.js
const swaggerDefinition = {
  openapi: '3.0.0',
  info: {
    title: 'MyNATCA Platform API',
    version: '1.0.0',
    description: 'MyNATCA Platform API Documentation'
  },
  servers: [
    { url: 'http://localhost:1300', description: 'Development' },
    { url: 'https://platform.natca.org', description: 'Production' }
  ],
  tags: [
    { name: 'Rackspace Email', description: 'Rackspace Email management endpoints' }
  ]
};
 
const options = {
  swaggerDefinition,
  apis: ['./routes/*.js'] // Includes rackspace.js
};

View Documentation

Access Swagger UI at:

Development: http://localhost:1300/api-docs (opens in a new tab)
Production: https://platform.natca.org/api-docs (opens in a new tab)

Look for the "Rackspace Email" tag in the Swagger interface.

Security Considerations

API Credential Security

Store API credentials as environment variables or secrets
Never commit credentials to version control
Use different credentials for development and production
Rotate API keys periodically
Restrict API key permissions to minimum required

Password Handling

Passwords are generated server-side only
Passwords displayed once to user and never stored in Platform
Use HTTPS for all API communications
Passwords meet Rackspace security requirements

Member Validation

All endpoints require Auth0 session authentication
Member eligibility validated before any Rackspace API calls
One email per member enforcement prevents abuse
Only Active and Retired NATCA members can receive emails

Error Handling

Sensitive information never exposed in error messages
Failed authentication attempts logged for security monitoring
Rate limiting prevents API abuse
Retry logic handles transient failures gracefully

Troubleshooting Setup

Issue: Invalid API Credentials

Symptoms: 401 Unauthorized errors from Rackspace API Solution:

Verify API Key and Secret Key are correct
Check Customer ID matches your account
Ensure no extra spaces in environment variables
Verify API key has not been revoked or expired

Issue: Signature Verification Failed

Symptoms: "Invalid signature" error from Rackspace API Solution:

Verify timestamp calculation is correct (Unix timestamp in seconds)
Check User-Agent matches exactly: 'MyNATCA Platform'
Ensure signature calculation includes all components in correct order
Verify SHA1 hash is hex-encoded

Issue: Environment Variables Not Loading

Symptoms: Undefined errors when accessing Rackspace credentials Solution:

Verify .env file exists in correct location
Ensure require('dotenv').config() is called in server.js
Check environment variables are set in deployment platform
Restart server after adding new environment variables

Issue: Mailbox Creation Fails

Symptoms: Error creating mailbox in Rackspace Solution:

Verify email format is valid (@natca.net domain)
Check password meets Rackspace requirements
Ensure mailbox doesn't already exist
Verify customer account has available mailbox quota