TypeScript SDK

npm install inboundemail
# or
bun add inboundemail
# or
yarn add inboundemail

import { Inbound } from 'inboundemail'

// Initialize with your API key
const inbound = new Inbound(process.env.INBOUND_API_KEY!)

// Send an email
const email = await inbound.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome!',
  html: '<p>Thanks for signing up!</p>'
})

import { Inbound } from 'inboundemail'

const inbound = new Inbound(apiKey: string)

await inbound.emails.send({ ... })

await inbound.domains.create({ domain: 'yourdomain.com' })
await inbound.domains.list()
await inbound.domains.get(domainId)
await inbound.domains.update(domainId, { ... })
await inbound.domains.delete(domainId)

await inbound.emailAddresses.create({ 
  address: '[email protected]',
  domainId: 'dom_123'
})
await inbound.emailAddresses.list()
await inbound.emailAddresses.get(emailAddressId)
await inbound.emailAddresses.update(emailAddressId, { ... })
await inbound.emailAddresses.delete(emailAddressId)

await inbound.endpoints.create({ 
  name: 'My Webhook',
  type: 'webhook',
  config: { url: 'https://yourapp.com/webhook' }
})
await inbound.endpoints.list()
await inbound.endpoints.get(endpointId)
await inbound.endpoints.update(endpointId, { ... })
await inbound.endpoints.delete(endpointId)
await inbound.endpoints.test(endpointId)

interface SendEmailRequest {
  from: string
  to: string | string[]
  subject: string
  html?: string
  text?: string
  cc?: string | string[]
  bcc?: string | string[]
  reply_to?: string | string[]
  headers?: Record<string, string>
  attachments?: Attachment[]
  tags?: EmailTag[]
  scheduled_at?: string
  timezone?: string
}

interface Attachment {
  filename: string
  content: string // Base64 encoded
  content_type?: string
  path?: string
}

interface EmailTag {
  name: string
  value: string
}

interface EmailSendResponse {
  id: string
  message_id?: string
  scheduled_at?: string
  status?: 'sent' | 'scheduled'
  timezone?: string
}

interface CreateDomainRequest {
  domain: string
}

interface Domain {
  id: string
  domain: string
  status: 'pending' | 'verified' | 'failed'
  canReceiveEmails: boolean
  hasMxRecords: boolean
  domainProvider: string | null
  providerConfidence: string | null
  mailFromDomain?: string
  mailFromDomainStatus?: string
  dnsRecords: DnsRecord[]
  dnsConflict?: DnsConflict
  createdAt: string
  updatedAt: string
  parentDomain?: string
  message?: string
}

interface DnsRecord {
  type: string
  name: string
  value: string
  description?: string
  isRequired: boolean
}

interface DnsConflict {
  hasConflict: boolean
  conflictType?: 'mx' | 'cname' | 'both'
  message: string
  existingRecords?: Array<{
    type: string
    value: string
  }>
}

interface CreateEmailAddressRequest {
  address: string
  domainId: string
  endpointId?: string
  webhookId?: string
  isActive?: boolean
}

interface EmailAddress {
  id: string
  address: string
  domainId: string
  webhookId: string | null
  endpointId: string | null
  isActive: boolean
  isReceiptRuleConfigured: boolean
  receiptRuleName: string | null
  createdAt: string
  updatedAt: string
  userId: string
  domain: {
    id: string
    name: string
    status: string
  }
  routing: {
    type: 'webhook' | 'endpoint' | 'none'
    id: string | null
    name: string | null
    config?: any
    isActive: boolean
  }
  warning?: string
}

interface CreateEndpointRequest {
  name: string
  type: 'webhook' | 'email' | 'email_group'
  config: WebhookConfig | EmailConfig | EmailGroupConfig
  description?: string
}

interface WebhookConfig {
  url: string
  timeout?: number // 1-300 seconds
  retryAttempts?: number // 0-10 attempts
  headers?: Record<string, string>
}

interface EmailConfig {
  forwardTo: string
  preserveHeaders?: boolean
}

interface EmailGroupConfig {
  emails: string[] // 1-50 emails
  preserveHeaders?: boolean
}

interface Endpoint {
  id: string
  name: string
  type: 'webhook' | 'email' | 'email_group'
  config: WebhookConfig | EmailConfig | EmailGroupConfig
  isActive: boolean
  description: string | null
  userId: string
  createdAt: string
  updatedAt: string
  groupEmails: string[] | null
  deliveryStats: {
    total: number
    successful: number
    failed: number
    lastDelivery: string | null
  }
}

interface InboundWebhookPayload {
  event: 'email.received' | string
  timestamp: string
  email: {
    id: string
    messageId: string
    from: InboundEmailAddress
    to: InboundEmailAddress
    recipient: string
    subject: string
    receivedAt: string
    threadId?: string | null
    threadPosition?: number | null
    parsedData: InboundParsedEmailData
    cleanedContent: InboundCleanedContent
  }
  endpoint: {
    id: string
    name: string
    type: 'webhook' | 'email' | 'email_group'
  }
}

interface InboundEmailAddress {
  text: string
  addresses: Array<{
    name: string | null
    address: string | null
  }>
}

interface InboundParsedEmailData {
  messageId: string
  date: Date
  subject: string
  from: InboundEmailAddress
  to: InboundEmailAddress
  cc: InboundEmailAddress | null
  bcc: InboundEmailAddress | null
  replyTo: InboundEmailAddress | null
  inReplyTo?: string
  references?: string | string[]
  textBody: string | null
  htmlBody: string | null
  raw: string
  attachments: unknown[]
  headers: Record<string, any>
  priority?: string
}

interface InboundCleanedContent {
  html: string | null
  text: string | null
  hasHtml: boolean
  hasText: boolean
  attachments: unknown[]
  headers: Record<string, any>
}

// Create a domain
const domain = await inbound.domains.create({
  domain: 'yourdomain.com'
})

console.log('Add these DNS records:')
domain.dnsRecords.forEach(record => {
  console.log(`${record.type}: ${record.name} -> ${record.value}`)
})

// List all domains
const domains = await inbound.domains.list()

// Get domain details
const domainDetails = await inbound.domains.get(domain.id)
console.log(`Status: ${domainDetails.status}`)

// Delete a domain
await inbound.domains.delete(domain.id)

// Create an email address with webhook routing
const emailAddr = await inbound.emailAddresses.create({
  address: '[email protected]',
  domainId: domain.id,
  endpointId: endpoint.id,
  isActive: true
})

console.log(`Created: ${emailAddr.address}`)
console.log(`Routing to: ${emailAddr.routing.name}`)

import { 
  Inbound, 
  type InboundWebhookPayload, 
  isInboundWebhookPayload 
} from 'inboundemail'
import { NextRequest, NextResponse } from 'next/server'

const inbound = new Inbound(process.env.INBOUND_API_KEY!)

export async function POST(request: NextRequest) {
  const payload: InboundWebhookPayload = await request.json()
  
  // Verify this is a valid Inbound webhook
  if (!isInboundWebhookPayload(payload)) {
    return NextResponse.json({ error: 'Invalid webhook' }, { status: 400 })
  }
  
  const { email } = payload
  console.log(`Received: ${email.subject} from ${email.from.addresses[0].address}`)
  
  // Auto-reply to support emails
  if (email.subject?.toLowerCase().includes('support')) {
    await inbound.reply(email, {
      from: '[email protected]',
      text: 'Thanks for contacting support! We\'ll get back to you within 24 hours.',
      tags: [{ name: 'type', value: 'auto-reply' }]
    })
  }
  
  return NextResponse.json({ success: true })
}

// Use idempotency keys to safely retry requests
const response = await fetch('https://inbound.new/api/e2/emails', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.INBOUND_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-123-confirmation'
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Order Confirmation',
    html: '<p>Your order has been confirmed!</p>'
  })
})

// If you retry with the same key, you'll get the same response