This is your first email!
',\n})\n\nif (error) {\n console.error('Failed to send email:', error)\n} else {\n console.log('Email sent:', email.id)\n}\n```\n\n## 🏗️ Unified Email API (New in v5.0.0)\n\nThe SDK now uses a unified email structure under `inbound.email.*`:\n\n```typescript\n// 📧 Received Email Management (NEW - unified under email.received)\ninbound.email.received.list() // List received emails\ninbound.email.received.get(id) // Get specific received email\ninbound.email.received.thread(id) // Get email thread\ninbound.email.received.markRead(id) // Mark as read\ninbound.email.received.archive(id) // Archive email\ninbound.email.received.reply(params) // Reply to received email\n\n// 📤 Sent Email Management (NEW - organized under email.sent)\ninbound.email.send(data) // Send email immediately\ninbound.email.schedule(data) // Schedule email\ninbound.email.sent.get(id) // Get sent email by ID\ninbound.email.sent.reply(id, data) // Reply to sent email\ninbound.email.sent.listScheduled() // List scheduled emails\ninbound.email.sent.getScheduled(id) // Get specific scheduled email\ninbound.email.sent.cancel(id) // Cancel scheduled email\n\n// 🔄 Universal Email Access\ninbound.email.get(id) // Get ANY email (received or sent)\n\n// 📮 Email Address Management (nested under email)\ninbound.email.address.create(data) // Create email address\ninbound.email.address.list() // List email addresses\ninbound.email.address.get(id) // Get address details\ninbound.email.address.update(id, data) // Update address routing\ninbound.email.address.delete(id) // Remove address\n\n// 🌐 Domain Management\ninbound.domain.create(data) // Add new domain\ninbound.domain.list() // List all domains\ninbound.domain.verify(id) // Verify domain\ninbound.domain.getDnsRecords(id) // Get DNS records\n\n// 🔗 Endpoint Management (Webhooks & Forwarding)\ninbound.endpoint.create(data) // Create endpoint\ninbound.endpoint.list() // List endpoints\ninbound.endpoint.test(id) // Test endpoint\n```\n\n### ⚠️ Deprecated Methods\n\nThe old `inbound.mail.*` methods are deprecated but still work with console warnings:\n\n```typescript\n// ❌ DEPRECATED - Will be removed in v6.0.0\ninbound.mail.list() // Use inbound.email.received.list() instead\ninbound.mail.get(id) // Use inbound.email.received.get() instead\ninbound.mail.markRead(id) // Use inbound.email.received.markRead() instead\n// ... etc\n```\n\n## 📊 Response Pattern\n\nAll methods now return a consistent `{ data, error }` pattern:\n\n```typescript\n// Success case\nconst { data, error } = await inbound.mail.list()\nif (error) {\n console.error('Error:', error)\n return\n}\nconsole.log('Emails:', data.emails)\n\n// Or with destructuring\nconst { data: emails, error: emailsError } = await inbound.mail.list()\nconst { data: domains, error: domainsError } = await inbound.domain.list()\n```\n\n## Streamlined Webhook Replies\n\nThe SDK includes a streamlined `reply()` method that makes it easy to reply to emails directly from webhook handlers:\n\n### Quick Setup\n\n```typescript\n// Works with either package name\nimport { Inbound, type InboundWebhookPayload, isInboundWebhook } from '@inboundemail/sdk'\n// import { Inbound, type InboundWebhookPayload, isInboundWebhook } from 'inbnd'\nimport { NextRequest, NextResponse } from 'next/server'\n\nconst inbound = new Inbound(process.env.INBOUND_API_KEY!)\n\nexport async function POST(request: NextRequest) {\n const payload: InboundWebhookPayload = await request.json()\n \n if (!isInboundWebhook(payload)) {\n return NextResponse.json({ error: 'Invalid webhook' }, { status: 400 })\n }\n \n const { email } = payload\n \n // Reply to emails with new { data, error } pattern\n const { data, error } = await inbound.reply(email, {\n from: 'support@yourdomain.com',\n text: 'Thanks for your message! We\\'ll get back to you soon.'\n })\n\n if (error) {\n console.error('Reply failed:', error)\n return NextResponse.json({ error }, { status: 500 })\n }\n\n return NextResponse.json({ success: true, messageId: data.messageId })\n}\n```\n\n## 📮 Email Address Management\n\nThe new hierarchical structure makes email address management more intuitive:\n\n```typescript\n// List all email addresses\nconst { data: addresses, error } = await inbound.email.address.list()\n\n// Create a new email address\nconst { data: newAddress, error: createError } = await inbound.email.address.create({\n address: 'support@yourdomain.com',\n domainId: 'domain-123'\n})\n\n// Update routing for an email address\nconst { data: updated, error: updateError } = await inbound.email.address.update('address-123', {\n endpointId: 'webhook-456',\n isActive: true\n})\n\n// Delete an email address\nconst { data: deleted, error: deleteError } = await inbound.email.address.delete('address-123')\n```\n\n## 🌐 Domain Management\n\n```typescript\n// Create and verify a domain\nconst { data: domain, error } = await inbound.domain.create({\n domain: 'yourdomain.com'\n})\n\nif (!error) {\n // Get DNS records needed for verification\n const { data: dnsRecords } = await inbound.domain.getDnsRecords(domain.id)\n console.log('Add these DNS records:', dnsRecords)\n \n // Verify domain after DNS setup\n const { data: verification } = await inbound.domain.verify(domain.id)\n}\n```\n\n## 🔗 Endpoint Management\n\n```typescript\n// Create a webhook endpoint\nconst { data: webhook, error } = await inbound.endpoint.create({\n name: 'My Webhook',\n type: 'webhook',\n config: {\n url: 'https://yourapp.com/webhook',\n timeout: 30000,\n retryAttempts: 3\n }\n})\n\n// Test the endpoint\nif (!error) {\n const { data: testResult } = await inbound.endpoint.test(webhook.id)\n console.log('Test result:', testResult)\n}\n```\n\n## 🎯 Convenience Methods\n\n```typescript\n// Quick reply to an email\nconst { data, error } = await inbound.quickReply(\n 'email-123', \n 'Thanks for your message!', \n 'support@yourdomain.com',\n { idempotencyKey: 'quick-reply-123' }\n)\n\n// One-step domain setup with webhook\nconst { data: setup } = await inbound.setupDomain(\n 'newdomain.com',\n 'https://yourapp.com/webhook'\n)\n\n// Create email forwarder\nconst { data: forwarder } = await inbound.createForwarder(\n 'info@yourdomain.com',\n 'team@yourdomain.com'\n)\n\n// Schedule a reminder\nconst { data: reminder } = await inbound.scheduleReminder(\n 'user@example.com',\n 'Meeting Tomorrow',\n 'tomorrow at 9am',\n 'reminders@yourdomain.com',\n { idempotencyKey: 'reminder-meeting-456' }\n)\n```\n\n## 🔄 Legacy Compatibility\n\nAll previous method names still work for backwards compatibility:\n\n```typescript\n// These are equivalent:\ninbound.email === inbound.emails\ninbound.domain === inbound.domains \ninbound.endpoint === inbound.endpoints\ninbound.email.address === inbound.emailAddresses\n\n// Legacy usage still works:\nconst { data } = await inbound.emails.send(emailData)\nconst { data } = await inbound.domains.list()\n```\n\n## 📧 Email Sending & Scheduling\n\n### Send Immediate Email\n\n```typescript\nconst { data: email, error } = await inbound.email.send({\n from: 'hello@yourdomain.com',\n to: ['user@example.com', 'admin@example.com'],\n subject: 'Welcome!',\n html: 'This email was scheduled!
',\n scheduled_at: 'in 1 hour', // Natural language\n timezone: 'America/New_York'\n})\n\n// Or with specific date\nconst { data: scheduled2 } = await inbound.email.schedule({\n from: 'hello@yourdomain.com',\n to: 'user@example.com',\n subject: 'New Year Email',\n html: 'Happy New Year!
',\n scheduled_at: '2024-01-01T00:00:00Z' // ISO 8601\n})\n```\n\n### Manage Scheduled Emails\n\n```typescript\n// List scheduled emails\nconst { data: scheduledEmails } = await inbound.email.listScheduled({\n status: 'scheduled',\n limit: 10\n})\n\n// Get specific scheduled email\nconst { data: scheduledEmail } = await inbound.email.getScheduled('email-id')\n\n// Cancel scheduled email\nconst { data: cancelled } = await inbound.email.cancel('email-id')\n```\n\n## 📬 Inbound Email Management\n\n```typescript\n// List received emails\nconst { data: emails } = await inbound.mail.list({\n limit: 50,\n status: 'processed',\n timeRange: '7d'\n})\n\n// Get specific email\nconst { data: email } = await inbound.mail.get('email-123')\n\n// Get email thread/conversation\nconst { data: thread } = await inbound.mail.thread('email-123')\n\n// Mark email as read/unread\nawait inbound.mail.markRead('email-123')\nawait inbound.mail.markUnread('email-123')\n\n// Archive/unarchive emails\nawait inbound.mail.archive('email-123')\nawait inbound.mail.unarchive('email-123')\n\n// Bulk operations\nconst { data: result } = await inbound.mail.bulk(\n ['email-1', 'email-2', 'email-3'],\n { isRead: true }\n)\n```\n\n## 🔧 Advanced Usage\n\n### React Email Components\n\n```typescript\nimport { EmailTemplate } from './EmailTemplate'\n\nconst { data, error } = await inbound.email.send({\n from: 'hello@yourdomain.com',\n to: 'user@example.com',\n subject: 'Welcome!',\n react: EmailTemplate({ name: 'John', welcomeUrl: 'https://app.com' })\n})\n```\n\n### Idempotency\n\nPrevent duplicate emails by using idempotency keys:\n\n```typescript\nconst { data, error } = await inbound.email.send({\n from: 'hello@yourdomain.com',\n to: 'user@example.com',\n subject: 'Important Email',\n text: 'This email will only be sent once'\n}, {\n idempotencyKey: 'unique-key-123'\n})\n\n// Works with all email sending methods\nawait inbound.email.schedule({\n from: 'hello@yourdomain.com',\n to: 'user@example.com',\n subject: 'Scheduled Email',\n text: 'This scheduled email is idempotent',\n scheduled_at: 'tomorrow at 9am'\n}, {\n idempotencyKey: 'scheduled-email-456'\n})\n\n// Also works with replies\nawait inbound.email.reply('email-123', {\n from: 'support@yourdomain.com',\n text: 'This reply will only be sent once'\n}, {\n idempotencyKey: 'reply-789'\n})\n```\n\n## 🛠️ Error Handling\n\n```typescript\nconst { data, error } = await inbound.email.send(emailData)\n\nif (error) {\n // Handle different error types\n if (error.includes('Invalid API key')) {\n console.error('Authentication failed')\n } else if (error.includes('Rate limit')) {\n console.error('Rate limit exceeded')\n } else {\n console.error('Unknown error:', error)\n }\n return\n}\n\n// Success case\nconsole.log('Email sent successfully:', data.id)\n```\n\n## 📚 TypeScript Support\n\nThe SDK is fully typed with TypeScript:\n\n```typescript\n// Type imports work with either package name\nimport type { \n ApiResponse,\n PostEmailsRequest,\n PostEmailsResponse,\n InboundWebhookPayload \n} from '@inboundemail/sdk'\n// } from 'inbnd'\n\n// Type-safe email sending\nconst emailRequest: PostEmailsRequest = {\n from: 'hello@yourdomain.com',\n to: 'user@example.com',\n subject: 'Typed Email',\n html: 'This is type-safe!
'\n}\n\nconst response: ApiResponse