Overview
Email addresses are specific addresses (like support@yourdomain.com) that can receive emails and route them to your configured endpoints.
List Email Addresses
Retrieve all configured email addresses:
import { Inbound } from '@inboundemail/sdk'
const inbound = new Inbound({ apiKey: process.env.INBOUND_API_KEY! })
// List all email addresses
const addresses = await inbound.emailAddresses.list()
// Filter by domain
const domainAddresses = await inbound.emailAddresses.list({
domainId: 'domain_abc123'
})
// Filter by status
const activeAddresses = await inbound.emailAddresses.list({
isActive: 'true',
isReceiptRuleConfigured: 'true'
})
List Parameters
Maximum number of results (1-100)
Number of results to skip
Filter by active status: true or false
Filter by AWS SES configuration status
Response Structure
interface EmailAddressWithDomain {
id: string
address: string
domainId: string
endpointId: string | null
isActive: boolean
isReceiptRuleConfigured: boolean
receiptRuleName: string | null
createdAt: Date
updatedAt: Date
domain: {
id: string
name: string
status: string
}
routing: {
type: 'webhook' | 'endpoint' | 'none'
id: string | null
name: string | null
config?: any
isActive: boolean
}
}
Create Email Address
Create a new email address to receive emails:
// Create with webhook endpoint
const emailAddress = await inbound.emailAddresses.create({
address: 'support@yourdomain.com',
domainId: 'domain_abc123',
endpointId: 'endp_xyz789',
isActive: true
})
console.log('Email address created:', emailAddress.address)
console.log('Routing to:', emailAddress.routing.type)
Create Parameters
ID of the verified domain
ID of the endpoint to route emails to
Whether the email address is active
The domain must be verified before you can create email addresses for it.
Get Email Address Details
const emailAddress = await inbound.emailAddresses.get('addr_abc123')
console.log('Address:', emailAddress.address)
console.log('Domain:', emailAddress.domain.name)
console.log('Active:', emailAddress.isActive)
console.log('Configured:', emailAddress.isReceiptRuleConfigured)
if (emailAddress.routing.type !== 'none') {
console.log('Routes to:', emailAddress.routing.name)
console.log('Endpoint active:', emailAddress.routing.isActive)
}
Update Email Address
// Change endpoint
const updated = await inbound.emailAddresses.update('addr_abc123', {
endpointId: 'endp_new789'
})
// Disable email address
const disabled = await inbound.emailAddresses.update('addr_abc123', {
isActive: false
})
// Remove endpoint (emails will bounce)
const unrouted = await inbound.emailAddresses.update('addr_abc123', {
endpointId: null
})
Update Parameters
Enable or disable the email address
Change or remove the endpoint routing
Delete Email Address
const result = await inbound.emailAddresses.delete('addr_abc123')
console.log('Deleted:', result.cleanup.emailAddress)
console.log('Domain:', result.cleanup.domain)
console.log('SES rule updated:', result.cleanup.sesRuleUpdated)
Deleting an email address will update AWS SES rules. Emails sent to deleted addresses will bounce.
Practical Examples
Department Email Setup
async function setupDepartmentEmails(domainId: string) {
const departments = [
{ name: 'support', endpoint: 'Support Team' },
{ name: 'sales', endpoint: 'Sales Team' },
{ name: 'billing', endpoint: 'Billing Team' },
{ name: 'info', endpoint: 'General Inquiries' }
]
// First, create endpoints for each department
const endpoints = await Promise.all(
departments.map(dept =>
inbound.endpoints.create({
name: dept.endpoint,
type: 'email_group',
config: {
emails: getTeamEmails(dept.name)
}
})
)
)
// Then create email addresses
const addresses = await Promise.all(
departments.map((dept, index) =>
inbound.emailAddresses.create({
address: `${dept.name}@yourdomain.com`,
domainId: domainId,
endpointId: endpoints[index].id
})
)
)
return addresses
}
Role-Based Email Addresses
// Standard role-based addresses
const roleAddresses = [
'admin', 'webmaster', 'postmaster',
'abuse', 'security', 'noreply'
]
async function createRoleAddresses(domain: string, domainId: string) {
// Create a catch-all endpoint for role addresses
const roleEndpoint = await inbound.endpoints.create({
name: 'Role-Based Addresses',
type: 'email',
config: {
email: 'admin@company.com'
}
})
// Create all role addresses
const addresses = await Promise.all(
roleAddresses.map(role =>
inbound.emailAddresses.create({
address: `${role}@${domain}`,
domainId: domainId,
endpointId: roleEndpoint.id
})
)
)
return addresses
}
Email Address Analytics
async function getEmailAddressStats() {
const addresses = await inbound.emailAddresses.list({
isActive: 'true'
})
const stats = {
total: addresses.data.length,
configured: addresses.data.filter(a => a.isReceiptRuleConfigured).length,
byDomain: {},
byRoutingType: {
webhook: 0,
endpoint: 0,
none: 0
}
}
addresses.data.forEach(address => {
// Count by domain
const domain = address.domain.name
stats.byDomain[domain] = (stats.byDomain[domain] || 0) + 1
// Count by routing type
stats.byRoutingType[address.routing.type]++
})
return stats
}
Temporary Email Addresses
async function createTempAddress(
purpose: string,
expiresInDays: number
) {
// Create email address
const tempAddress = await inbound.emailAddresses.create({
address: `temp-${Date.now()}@yourdomain.com`,
domainId: 'domain_abc123',
endpointId: 'endp_temp123'
})
// Schedule deletion
setTimeout(async () => {
await inbound.emailAddresses.delete(tempAddress.id)
console.log(`Deleted temporary address: ${tempAddress.address}`)
}, expiresInDays * 24 * 60 * 60 * 1000)
return {
address: tempAddress.address,
expiresAt: new Date(Date.now() + expiresInDays * 24 * 60 * 60 * 1000)
}
}
Migration Helper
async function migrateEmailAddresses(
fromEndpointId: string,
toEndpointId: string
) {
// Get all addresses using the old endpoint
const allAddresses = await inbound.emailAddresses.list()
const addressesToMigrate = allAddresses.data.filter(
addr => addr.endpointId === fromEndpointId
)
console.log(`Migrating ${addressesToMigrate.length} addresses...`)
// Update each address
const results = await Promise.allSettled(
addressesToMigrate.map(addr =>
inbound.emailAddresses.update(addr.id, {
endpointId: toEndpointId
})
)
)
const successful = results.filter(r => r.status === 'fulfilled').length
const failed = results.filter(r => r.status === 'rejected').length
console.log(`Migration complete: ${successful} successful, ${failed} failed`)
return { successful, failed, results }
}
Best Practices
- Use descriptive email addresses that indicate their purpose
- Always configure an endpoint before emails arrive
- Monitor isReceiptRuleConfigured to ensure AWS SES is properly set up
- Consider using catch-all addresses for domains instead of many individual addresses
- Implement proper access control for sensitive addresses like admin@
- Regularly audit unused email addresses and remove them
Error Handling
try {
await inbound.emailAddresses.create({
address: 'test@unverified-domain.com',
domainId: 'domain_invalid'
})
} catch (error) {
if (error.message.includes('domain not found')) {
console.error('Domain must be verified first')
} else if (error.message.includes('already exists')) {
console.error('Email address already exists')
} else {
console.error('Failed to create address:', error.message)
}
}
Next Steps
