Emailinbound

SDK and API Docs

Get started with the Inbound Email API in minutes

1. Get Your API Key

Create an API key from your Settings page.

2. Install the SDK (Optional)

npm install exon-inbound

3. Make Your First Request

import { createInboundClient } from 'exon-inbound'

const inbound = createInboundClient({
  apiKey: 'your_api_key_here'
})

// List your domains
const domains = await inbound.getDomains()
console.log('Your domains:', domains)

// Find a verified domain
const verifiedDomain = domains.find(d => 
  d.status === 'verified' && d.canReceiveEmails
)

if (verifiedDomain) {
  console.log('Ready to use:', verifiedDomain.domain)
}

Authentication

All API requests require authentication using an API key

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Security: Keep your API keys secure and never expose them in client-side code.

Domains

Manage your email domains and get domain information for email operations

List Domains

Get all domains for your account with their IDs and status information.

Request

// Get just the domains array
const domains = await inbound.getDomains()

// or use the explicit method
const domains = await inbound.listDomains()

// Find a specific domain by name
const myDomain = domains.find(d => d.domain === 'example.com')
console.log('Domain ID:', myDomain?.id) // Use this ID for email operations

Response

[
  {
    "id": "indm_abc123",
    "domain": "example.com",
    "status": "verified",
    "canReceiveEmails": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  {
    "id": "indm_def456",
    "domain": "myapp.com",
    "status": "pending",
    "canReceiveEmails": false,
    "createdAt": "2024-01-02T00:00:00.000Z",
    "updatedAt": "2024-01-02T00:00:00.000Z"
  }
]

Domain Status

Understanding domain status values and what they mean.

verified
Domain is verified and can receive emails
pending
Domain verification is in progress
failed
Domain verification failed
ses_pending
Waiting for AWS SES verification

Note: Only domains with status: "verified" and canReceiveEmails: true can be used to create email addresses.

Using Domain Information

How to use domain data for email address operations.

// Complete workflow: List domains and create email addresses
async function setupEmailAddresses() {
  // 1. Get all domains
  const domains = await inbound.getDomains()
  
  // 2. Find verified domains that can receive emails
  const verifiedDomains = domains.filter(d => 
    d.status === 'verified' && d.canReceiveEmails
  )
  
  if (verifiedDomains.length === 0) {
    throw new Error('No verified domains available')
  }
  
  // 3. Use the first verified domain
  const domain = verifiedDomains[0]
  console.log(`Using domain: ${domain.domain} (ID: ${domain.id})`)
  
  // 4. Create email addresses on this domain
  const emails = [
    'support@' + domain.domain,
    'hello@' + domain.domain,
    'contact@' + domain.domain
  ]
  
  for (const emailAddress of emails) {
    const email = await inbound.addEmail(
      domain.domain,  // Use domain name
      emailAddress,   // Full email address
      'webhook_123'   // Optional webhook ID
    )
    console.log(`Created: ${email.address}`)
  }
  
  return { domain, emailsCreated: emails.length }
}

Email Addresses

Create and manage email addresses on your domains

Create Email Address

Add a new email address to a verified domain.

Request

// Method 1: Using createEmail
const email = await inbound.createEmail({
  domain: 'example.com',
  email: 'hello@example.com',
  webhookId: 'webhook_123' // optional
})

// Method 2: Using convenience method
const email = await inbound.addEmail(
  'example.com',
  'hello@example.com',
  'webhook_123' // optional
)

Response

{
  "id": "email_abc123",
  "address": "hello@example.com",
  "domainId": "indm_abc123",
  "webhookId": "webhook_123",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

List Email Addresses

Get all email addresses for a specific domain.

Request

// Get just the emails array
const emails = await inbound.getEmails('example.com')

// Get full response with domain info
const response = await inbound.listEmails('example.com')
console.log(response.domain) // 'example.com'
console.log(response.emails) // EmailAddress[]

Response

[
  {
    "id": "email_abc123",
    "address": "hello@example.com",
    "webhookId": "webhook_123",
    "isActive": true,
    "isReceiptRuleConfigured": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

Delete Email Address

Remove an email address from a domain.

Request

const result = await inbound.deleteEmail('example.com', 'hello@example.com')
// or
const result = await inbound.removeEmail('example.com', 'hello@example.com')

console.log(result.message)

Response

{
  "message": "Email address hello@example.com removed from domain example.com"
}

Webhooks

Create and manage webhook endpoints for email processing

Create Webhook

Create a new webhook endpoint to receive email notifications.

Request

// Method 1: Using createWebhook
const webhook = await inbound.createWebhook({
  name: 'Email Processor',
  endpoint: 'https://api.example.com/webhook',
  description: 'Processes incoming emails',
  retry: 3,
  timeout: 30
})

// Method 2: Using convenience method
const webhook = await inbound.addWebhook(
  'Email Processor',
  'https://api.example.com/webhook',
  {
    description: 'Processes incoming emails',
    retry: 3,
    timeout: 30
  }
)

Response

{
  "id": "webhook_abc123",
  "name": "Email Processor",
  "url": "https://api.example.com/webhook",
  "secret": "webhook_secret_for_verification",
  "description": "Processes incoming emails",
  "isActive": true,
  "timeout": 30,
  "retryAttempts": 3,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

List Webhooks

Get all webhooks for your account.

Request

const webhooks = await inbound.getWebhooks()
// or
const webhooks = await inbound.listWebhooks()

Response

[
  {
    "id": "webhook_abc123",
    "name": "Email Processor",
    "url": "https://api.example.com/webhook",
    "description": "Processes incoming emails",
    "isActive": true,
    "timeout": 30,
    "retryAttempts": 3,
    "totalDeliveries": 150,
    "successfulDeliveries": 145,
    "failedDeliveries": 5,
    "lastUsed": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

Delete Webhook

Remove a webhook by name.

Request

const result = await inbound.deleteWebhook('Email Processor')
// or
const result = await inbound.removeWebhook('Email Processor')

console.log(result.message)

Response

{
  "message": "Webhook 'Email Processor' has been removed"
}

Error Handling

Understanding API errors and how to handle them

HTTP Status Codes

200
Success
201
Created
400
Bad Request
401
Unauthorized
404
Not Found
409
Conflict
500
Internal Server Error

Error Response Format

{
  "error": "Error message describing what went wrong"
}

TypeScript Error Handling

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

A full example showing how to set up email infrastructure

import { createInboundClient, InboundError } from 'exon-inbound'

async function setupEmailInfrastructure() {
  const inbound = createInboundClient({
    apiKey: process.env.INBOUND_API_KEY!
  })

  try {
    // 1. List existing domains and find verified ones
    const domains = await inbound.getDomains()
    console.log('Available domains:', domains.map(d => `${d.domain} (${d.status})`))
    
    // Find a verified domain that can receive emails
    const verifiedDomain = domains.find(d => 
      d.status === 'verified' && d.canReceiveEmails
    )
    
    if (!verifiedDomain) {
      throw new Error('No verified domains available. Please verify a domain first.')
    }
    
    console.log(`Using domain: ${verifiedDomain.domain} (ID: ${verifiedDomain.id})`)

    // 2. Create a webhook
    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)

    // 3. Create email addresses on the verified domain
    const emailPrefixes = ['support', 'hello', 'contact']
    const createdEmails = []

    for (const prefix of emailPrefixes) {
      const emailAddress = `${prefix}@${verifiedDomain.domain}`
      const email = await inbound.addEmail(
        verifiedDomain.domain,  // Use the domain name
        emailAddress,           // Full email address
        webhook.id              // Assign the webhook
      )
      createdEmails.push(email)
      console.log(`Created email: ${email.address}`)
    }

    // 4. List all emails for the domain
    const domainEmails = await inbound.getEmails(verifiedDomain.domain)
    console.log(`Total emails for ${verifiedDomain.domain}: ${domainEmails.length}`)

    // 5. List all webhooks
    const allWebhooks = await inbound.getWebhooks()
    console.log(`Total webhooks: ${allWebhooks.length}`)

    // 6. Summary
    console.log('\n📊 Setup Summary:')
    console.log(`✅ Domain: ${verifiedDomain.domain}`)
    console.log(`✅ Webhook: ${webhook.name}`)
    console.log(`✅ Email addresses: ${createdEmails.length}`)
    
    return {
      domain: verifiedDomain,
      webhook,
      emails: createdEmails
    }

  } 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)
    }
    throw error
  }
}

setupEmailInfrastructure()

Need help? Check out our Settings page to create API keys or contact support.