Skip to main content

​
Quickstart Guide

Get Inbound up and running in your application in less than 5 minutes. This guide will walk you through installing the SDK, setting up your first domain, and receiving your first webhook.
You’ll need an API key from inbound.new to follow this guide.
1

Install the SDK

Install the Inbound SDK using your preferred package manager:
npm install inboundemail
The SDK is fully typed with TypeScript and works with Node.js, Bun, and all modern JavaScript frameworks.
2

Initialize with your API key

Create an Inbound client with your API key. Get your key from inbound.new.
import { Inbound } from 'inboundemail'

// Get your API key from inbound.new
const inbound = new Inbound(process.env.INBOUND_API_KEY)
Store your API key in environment variables - never commit it to version control.
3

Add your domain

Add a domain to start receiving emails. Inbound will provide DNS records to configure.
const domain = await inbound.domains.create({
  domain: "yourdomain.com"
})

console.log("Domain added:", domain.domain)
console.log("Configure these DNS records:", domain.dnsRecords)
After adding your domain, you’ll receive DNS records to add to your domain provider:
  • MX Record: Routes incoming email to Inbound
  • TXT Record: Verifies domain ownership
  • DKIM Records: Improves email deliverability
Domain verification is automatic once DNS records are configured. Check status with inbound.domains.get(domain.id).
4

Create an email address

Create an email address that triggers a webhook when it receives mail.
const emailAddress = await inbound.emailAddresses.create({
  address: "[email protected]",
  webhookUrl: "https://yourapp.com/webhook/email"
})

console.log("Email address created:", emailAddress.address)
console.log("Webhook URL:", emailAddress.webhookUrl)
Your webhook URL must be publicly accessible and return a 200 status code within 30 seconds.
5

Handle incoming webhooks

Create a webhook endpoint to receive and process incoming emails.
import { Inbound, isInboundWebhookPayload } from 'inboundemail'
import { NextRequest, NextResponse } from 'next/server'

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

export async function POST(request: NextRequest) {
  try {
    const payload = 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: ${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 })
  } catch (error) {
    console.error('Webhook error:', error)
    return NextResponse.json({ error: 'Webhook processing failed' }, { status: 500 })
  }
}
The webhook payload includes:
  • Parsed email content: Subject, sender, recipients, HTML and text body
  • Attachments: Download URLs for all attachments
  • Headers: Full email headers for advanced processing
  • Metadata: Message ID, timestamps, and routing information
Use the inbound.reply() method to reply to emails while maintaining the conversation thread.
6

Test your setup

Send a test email to verify everything is working:
# Send a test email from the command line
echo "Test email body" | mail -s "Test Subject" [email protected]
Or use the test webhook script from the Inbound repository:
bun run inbound-webhook-test [email protected]
Check your webhook endpoint logs to see the parsed email content.

​
What’s Next?

Send Emails

Learn how to send transactional emails with tags and attachments

Email Threading

Handle email threads and conversations automatically

Webhook Security

Verify webhook signatures to ensure requests are from Inbound

API Reference

Explore the complete API documentation

​
Common Use Cases

Create a support ticket from every email sent to [email protected]:
export async function POST(request: NextRequest) {
  const payload = await request.json()
  
  if (!isInboundWebhookPayload(payload)) {
    return NextResponse.json({ error: 'Invalid webhook' }, { status: 400 })
  }
  
  const { email } = payload
  
  // Create support ticket
  const ticket = await createTicket({
    from: email.from?.addresses?.[0]?.address,
    subject: email.subject,
    content: email.cleanedContent.text,
    attachments: email.cleanedContent.attachments
  })
  
  // Send confirmation email
  await inbound.reply(email, {
    from: '[email protected]',
    html: `<p>Thanks for contacting support! Your ticket #${ticket.id} has been created.</p>`
  })
  
  return NextResponse.json({ success: true, ticketId: ticket.id })
}
Convert emails to tasks in your project management tool:
export async function POST(request: NextRequest) {
  const payload = await request.json()
  
  if (!isInboundWebhookPayload(payload)) {
    return NextResponse.json({ error: 'Invalid webhook' }, { status: 400 })
  }
  
  const { email } = payload
  
  // Parse task from email subject
  const taskTitle = email.subject?.replace(/^task:/i, '').trim()
  
  // Create task in your system
  const task = await createTask({
    title: taskTitle,
    description: email.cleanedContent.text,
    assignee: email.from?.addresses?.[0]?.address,
    attachments: email.cleanedContent.attachments.map(a => a.downloadUrl)
  })
  
  return NextResponse.json({ success: true, taskId: task.id })
}
Process replies to your newsletters and handle unsubscribes:
export async function POST(request: NextRequest) {
  const payload = await request.json()
  
  if (!isInboundWebhookPayload(payload)) {
    return NextResponse.json({ error: 'Invalid webhook' }, { status: 400 })
  }
  
  const { email } = payload
  const senderEmail = email.from?.addresses?.[0]?.address
  
  // Handle unsubscribe requests
  if (email.subject?.toLowerCase().includes('unsubscribe') || 
      email.cleanedContent.text?.toLowerCase().includes('unsubscribe')) {
    await unsubscribeUser(senderEmail)
    
    await inbound.reply(email, {
      from: '[email protected]',
      text: 'You have been unsubscribed from our newsletter.'
    })
    
    return NextResponse.json({ success: true, action: 'unsubscribed' })
  }
  
  // Log other replies for review
  await logNewsletterReply({
    from: senderEmail,
    subject: email.subject,
    content: email.cleanedContent.text
  })
  
  return NextResponse.json({ success: true, action: 'logged' })
}

​
Need Help?

Join the Community

Get help from the Inbound community and share your use cases
Having issues? Check your webhook endpoint returns a 200 status code and your DNS records are properly configured.

Build docs developers (and LLMs) love

Get started for freeTalk to us