Skip to main content

Getting Started with Relay

This guide walks you through initial setup: accessing Relay, verifying a sending domain, creating an API key, and sending your first email.

Accessing Relay​

  1. Log in to The One Stack at your Hub URL
  2. Click the waffle menu (grid icon) in the top-left corner of the Hub Bar
  3. Select Relay from the product list
  4. You'll land on the Relay Dashboard showing today's stats and domain health
ℹ️Relay requires the Relay product entitlement on your organization. Contact your account administrator if you don't see Relay in the product menu.

Initial Setup Checklist​

Before sending your first email, complete these steps:

  1. Verify a sending domain — Add and verify at least one domain with proper DNS records
  2. Create an API key — Generate a key with send scope for your application
  3. Configure settings — Set your bounce rate threshold and notification preferences
  4. Send a test email — Verify everything works end-to-end

Key Concepts​

TermDefinition
Sending domainA domain you own (e.g., yourmsp.com) that's verified with SPF, DKIM, and DMARC records for email authentication
API keyA scoped credential used to authenticate API requests. Each key has specific permissions (send, read-logs, etc.)
SuppressionAn email address blocked from receiving future emails, either automatically (bounce/complaint) or manually
TemplateA reusable email layout with {{variable}} placeholders that get replaced at send time
Inbound routingIncoming emails to special addresses (e.g., [email protected]) that auto-route to PSA, CRM, or Portal
Rate limitPer-tenant sending limits across four time windows to prevent abuse and maintain SES reputation
Bounce ratePercentage of sent emails that bounced. SES requires this stays below 5%

Step 1: Add a Sending Domain​

  1. Navigate to Domains in the left sidebar
  2. Click Add Domain
  3. Enter your domain name (e.g., yourmsp.com)
  4. Relay generates the required DNS records:
    • 3 CNAME records for DKIM authentication
    • 1 TXT record for SPF
    • 1 TXT record for DMARC
  5. Click the copy icon next to each record and add them to your DNS provider
  6. Click Verify — Relay checks DNS propagation and marks verified records with a green checkmark
💡DNS propagation can take up to 48 hours, but most changes propagate within 15-30 minutes. If verification fails, wait and try again.

See Domain Setup for detailed instructions on DNS configuration.

Step 2: Create an API Key​

  1. Navigate to API Keys in the left sidebar
  2. Click Create Key
  3. Enter a descriptive name (e.g., PSA Notifications - Production)
  4. Select scopes — at minimum, check send for sending emails
  5. Optionally set an expiration date
  6. Click Create
  7. Copy the key immediately — it's only shown once
⚠️Store your API key securely. It cannot be retrieved after creation. If lost, revoke the key and create a new one.

See API Keys for scope details and best practices.

Step 3: Send Your First Email​

Using the API with your new key:

curl -X POST https://api.theonerelay.app/api/send \
  -H "Content-Type: application/json" \
  -H "X-Relay-Key: your_api_key_here" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Test from Relay",
    "html": "<h1>Hello!</h1><p>Your Relay setup is working.</p>",
    "text": "Hello! Your Relay setup is working."
  }'

A successful response returns:

{
  "message_id": "msg_abc123...",
  "status": "sent",
  "ses_message_id": "0100018e..."
}

Or using the TypeScript SDK:

import { RelayClient } from '@theonefamily/relay-sdk';

const relay = new RelayClient({
  apiKey: process.env.RELAY_API_KEY,
});

const result = await relay.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Test from Relay',
  html: '<h1>Hello!</h1><p>Your Relay setup is working.</p>',
  text: 'Hello! Your Relay setup is working.',
});

Step 4: Verify Delivery​

  1. Navigate to Email Logs in the left sidebar
  2. Find your test email in the list
  3. Confirm the status shows Delivered (green badge)
  4. Check the Dashboard — your sent and delivered counts should increment

What's Next​