TypeScript SDK

Official TypeScript SDK for Relay with full type safety and automatic validation.

Installation

Install the SDK using your preferred package manager:

npm install @voidvalue/relay

Prerequisites: You need an API key and SMTP key from your Relay dashboard.

Quick Start

Get started with the Relay SDK in just a few lines of code:

import { RelayClient } from '@voidvalue/relay'

const relay = new RelayClient({
  apiKey: 'your-api-key',
  smtpKey: 'your-smtp-key',
})

await relay.send({
  to: '[email protected]',
  subject: 'Hello World',
  content: 'This is a test email',
})

Sending Emails

Send emails to single or multiple recipients with HTML or plain text content:

// Single recipient
await relay.send({
  to: '[email protected]',
  subject: 'Hello',
  content: 'Plain text content',
})

// Multiple recipients
await relay.send({
  to: ['[email protected]', '[email protected]'],
  subject: 'Newsletter',
  content: 'Monthly newsletter content',
})

// HTML email
await relay.send({
  to: '[email protected]',
  subject: 'Welcome',
  content: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  isHtml: true,
})

Batch Emails

Send up to 50 different emails in a single request:

const response = await relay.sendBatch({
  emails: [
    {
      to: '[email protected]',
      subject: 'Personal Message 1',
      content: 'Hello User 1',
    },
    {
      to: '[email protected]',
      subject: 'Personal Message 2',
      content: 'Hello User 2',
    },
  ],
})

console.log(response.batchId)
console.log(response.successCount)
console.log(response.failureCount)

Email Logs

Query email logs with filtering and pagination:

// List logs with pagination
const logs = await relay.listLogs({
  page: 1,
  limit: 50,
  status: 'delivered',
})

logs.logs.forEach((log) => {
  console.log(log.id, log.to, log.status)
})

// Filter by status
const pending = await relay.listLogs({ status: 'pending' })
const delivered = await relay.listLogs({ status: 'delivered' })
const failed = await relay.listLogs({ status: 'failed' })

// Filter by batch
const batchLogs = await relay.listLogs({ batchId: 'batch_12345' })

// Get single email details
const email = await relay.getLog('email_id')
console.log(email.content)
console.log(email.status)
console.log(email.openCount)
console.log(email.smtpConfig)

Email Validation

The SDK automatically validates email addresses before making API requests:

import { isValidEmail } from '@voidvalue/relay'

// Manual email validation
if (isValidEmail('[email protected]')) {
  console.log('Valid email')
}

// Automatic validation on send
try {
  await relay.send({
    to: 'invalid-email',
    subject: 'Test',
    content: 'This will fail before the API call',
  })
} catch (error) {
  console.error(error.message) // Invalid email address
}

Webhook Verification

Verify webhook signatures to ensure they come from Relay:

const result = await relay.verifyWebhook({
  signature: 'webhook-signature-from-header',
  payload: 'webhook-payload-body',
})

if (result.valid) {
  console.log('Webhook signature is valid')
  // Process webhook event
} else {
  console.log('Invalid webhook signature')
}

Error Handling

Handle errors gracefully with typed error responses:

import { RelayClient, RelayError } from '@voidvalue/relay'

const relay = new RelayClient({
  apiKey: 'your-api-key',
  smtpKey: 'your-smtp-key',
})

try {
  await relay.send({
    to: '[email protected]',
    subject: 'Test',
    content: 'Test content',
  })
} catch (error) {
  if (error instanceof RelayError) {
    // API error
    console.error('Status:', error.statusCode)
    console.error('Message:', error.message)
    console.error('Response:', error.response)
  } else {
    // Validation error
    console.error('Validation Error:', error.message)
  }
}

TypeScript Types

All types are exported for use in your TypeScript projects:

import type {
  SendEmailRequest,
  SendEmailResponse,
  BatchEmailRequest,
  BatchEmailResponse,
  EmailLogQuery,
  EmailLogResponse,
  EmailDetailResponse,
  EmailStatus,
  WebhookVerifyRequest,
  WebhookVerifyResponse,
  HealthResponse,
} from '@voidvalue/relay'

// Use types in your application
const emailRequest: SendEmailRequest = {
  to: '[email protected]',
  subject: 'Hello',
  content: 'Welcome',
  isHtml: false,
}

API Limits

Single email: 1-100 recipients
Batch emails: 1-50 emails per batch
Subject: 1-998 characters
Content: Up to 1,000,000 characters
Log list: Maximum 100 per page

Full Documentation: For more details, visit the SDK on npm