exon-inbound
Official TypeScript SDK for the Inbound Email API. Easily manage email domains, email addresses, and webhooks programmatically.
Installation
npm install exon-inbound
yarn add exon-inbound
pnpm add exon-inbound
bun add exon-inbound
Quick Start
import { createInboundClient } from 'exon-inbound'
const inbound = createInboundClient({
apiKey: 'your_api_key_here',
baseUrl: 'https://your-domain.com/api/v1'
})
const email = await inbound.createEmail({
domain: 'example.com',
email: 'hello@example.com',
webhookId: 'webhook_123'
})
console.log('Created email:', email.address)
API Reference
Client Initialization
import { InboundClient, createInboundClient } from 'exon-inbound'
const inbound = createInboundClient({
apiKey: 'your_api_key',
baseUrl: 'https://api.inbound.email/api/v1'
})
const inbound = new InboundClient({
apiKey: 'your_api_key',
baseUrl: 'https://api.inbound.email/api/v1'
})
Domain Management
List Domains
const domains = await inbound.listDomains()
const domains = await inbound.getDomains()
console.log(domains)
Email Address Management
Create Email Address
const email = await inbound.createEmail({
domain: 'example.com',
email: 'support@example.com',
webhookId: 'webhook_123'
})
const email = await inbound.addEmail(
'example.com',
'support@example.com',
'webhook_123'
)
console.log(email)
List Email Addresses
const response = await inbound.listEmails('example.com')
console.log(response.domain)
console.log(response.emails)
const emails = await inbound.getEmails('example.com')
console.log(emails)
Remove Email Address
const result = await inbound.removeEmail('example.com', 'support@example.com')
const result = await inbound.deleteEmail('example.com', 'support@example.com')
console.log(result.message)
Webhook Management
Create Webhook
const webhook = await inbound.createWebhook({
name: 'My Webhook',
endpoint: 'https://api.example.com/webhook',
description: 'Processes incoming emails',
retry: 3,
timeout: 30
})
const webhook = await inbound.addWebhook(
'My Webhook',
'https://api.example.com/webhook',
{
description: 'Processes incoming emails',
retry: 3,
timeout: 30
}
)
console.log(webhook)
List Webhooks
const webhooks = await inbound.listWebhooks()
const webhooks = await inbound.getWebhooks()
console.log(webhooks)
Remove Webhook
const result = await inbound.removeWebhook('My Webhook')
const result = await inbound.deleteWebhook('My Webhook')
console.log(result.message)
Error Handling
The SDK throws InboundError
for API errors:
import { InboundError } from 'exon-inbound'
try {
const email = await inbound.createEmail({
domain: 'nonexistent.com',
email: 'test@nonexistent.com'
})
} catch (error) {
if (error instanceof InboundError) {
console.error('API Error:', error.message)
console.error('Status:', error.status)
console.error('Code:', error.code)
} else {
console.error('Unexpected error:', error)
}
}
Complete Example
import { createInboundClient, InboundError } from 'exon-inbound'
async function setupEmailInfrastructure() {
const inbound = createInboundClient({
apiKey: process.env.INBOUND_API_KEY!
})
try {
const domains = await inbound.getDomains()
console.log('Available domains:', domains.map(d => d.domain))
const webhook = await inbound.addWebhook(
'Email Processor',
'https://api.myapp.com/process-email',
{
description: 'Processes all incoming emails',
timeout: 30,
retry: 3
}
)
console.log('Created webhook:', webhook.name)
console.log('Webhook secret:', webhook.secret)
const emails = [
'support@example.com',
'hello@example.com',
'contact@example.com'
]
for (const emailAddress of emails) {
const email = await inbound.addEmail(
'example.com',
emailAddress,
webhook.id
)
console.log(`Created email: ${email.address}`)
}
const domainEmails = await inbound.getEmails('example.com')
console.log(`Total emails for example.com: ${domainEmails.length}`)
const allWebhooks = await inbound.getWebhooks()
console.log(`Total webhooks: ${allWebhooks.length}`)
} catch (error) {
if (error instanceof InboundError) {
console.error('Inbound API Error:', error.message)
if (error.status) {
console.error('HTTP Status:', error.status)
}
} else {
console.error('Unexpected error:', error)
}
}
}
setupEmailInfrastructure()
TypeScript Support
The SDK is written in TypeScript and provides full type safety:
import { Domain, EmailAddress, Webhook, InboundClient } from 'exon-inbound'
const domains: Domain[] = await inbound.getDomains()
const emails: EmailAddress[] = await inbound.getEmails('example.com')
const webhooks: Webhook[] = await inbound.getWebhooks()
const client: InboundClient = createInboundClient({
apiKey: 'your_key',
baseUrl: 'https://api.example.com/v1'
})
Environment Variables
For security, store your API key in environment variables:
INBOUND_API_KEY=your_api_key_here
const inbound = createInboundClient({
apiKey: process.env.INBOUND_API_KEY!
})
API Methods Summary
listDomains() / getDomains() | Get all domains | Domain[] |
createEmail(params) / addEmail(domain, email, webhookId?) | Create email address | EmailAddress |
listEmails(domain) | Get emails for domain | DomainEmailsResponse |
getEmails(domain) | Get emails array for domain | EmailAddress[] |
removeEmail(domain, email) / deleteEmail(domain, email) | Remove email address | {message: string} |
listWebhooks() / getWebhooks() | Get all webhooks | Webhook[] |
createWebhook(params) / addWebhook(name, endpoint, options?) | Create webhook | WebhookCreateResponse |
removeWebhook(name) / deleteWebhook(name) | Remove webhook | {message: string} |
Requirements
- Node.js 16.0.0 or higher
- Valid Inbound Email API key
License
MIT
Support
For issues and questions: