Relay SDK

TypeScript SDK for the Relay Email API at relay.voidvalue.com.

Features

• Type-safe API with full TypeScript support
• Automatic email validation before API requests
• Send single emails or batch up to 50 emails
• Query email logs with filtering and pagination
• Webhook signature verification
• Health check endpoint
• Comprehensive error handling
• Zero dependencies

Prerequisites

Before using this SDK, you need to register an account at relay.voidvalue.com to obtain your API credentials.

Important

This SDK always uses the latest API version. If you need to use an older API version, you must interact with the API directly.

Installation

npm install @voidvalue/relay

pnpm add @voidvalue/relay

yarn add @voidvalue/relay

Quick Start

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',
})

Email Validation

The SDK automatically validates all email addresses before making API requests. If an invalid email is provided, an error is thrown before the request is sent.

try {
	await relay.send({
		to: 'invalid-email',
		subject: 'Test',
		content: 'This will fail',
	})
} catch (error) {
	console.error(error.message)
}

You can also manually check if an email is valid:

import { isValidEmail } from '@voidvalue/relay'

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

Sending Emails

Single Email

const response = await relay.send({
	to: '[email protected]',
	subject: 'Hello',
	content: 'Plain text content',
})

console.log(response.emailIds)
console.log(response.trackingIds)
console.log(response.recipientCount)

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 one 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',
		},
	],
	isHtml: false,
})

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

Email Logs

List Logs

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

const email = await relay.getLog('email_id')

console.log(email.content)
console.log(email.status)
console.log(email.openCount)
console.log(email.smtpConfig)

Webhook Verification

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

if (result.valid) {
	console.log('Webhook signature is valid')
}

Health Check

const health = await relay.checkHealth()

console.log(health.status)
console.log(health.database)
console.log(health.timestamp)

Error Handling

The SDK throws errors in two cases:

1. Email validation fails before the API request
2. The API request fails

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

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

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

TypeScript Support

All types are exported and available for use:

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

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Website: relay.voidvalue.com

License

MIT