Overview
Endpoints define where incoming emails are routed. Inbound supports three endpoint types:
- Webhooks - Send email data to your HTTP endpoints
- Email - Forward to a single email address
- Email Groups - Forward to multiple email addresses
List Endpoints
Retrieve all configured endpoints:
import { Inbound } from '@inboundemail/sdk'
const inbound = new Inbound({ apiKey: process.env.INBOUND_API_KEY! })
// List all endpoints
const endpoints = await inbound.endpoints.list()
// Filter by type
const webhooks = await inbound.endpoints.list({
type: 'webhook',
active: 'true'
})
// With pagination
const paginatedEndpoints = await inbound.endpoints.list({
limit: 20,
offset: 0
})
List Parameters
Maximum number of results (1-100)
Number of results to skip
Filter by type: webhook
, email
, email_group
Filter by status: true
or false
Create Endpoint
Create Webhook Endpoint
const webhook = await inbound.endpoints.create({
name: 'Production Webhook',
type: 'webhook',
description: 'Main webhook for production emails',
config: {
url: 'https://api.yourdomain.com/webhook',
timeout: 30,
retryAttempts: 3,
headers: {
'X-API-Key': 'your-secret-key'
}
}
})
console.log('Webhook created:', webhook.id)
Create Email Forward
const emailForward = await inbound.endpoints.create({
name: 'Support Forward',
type: 'email',
description: 'Forward to support team',
config: {
email: 'support@yourdomain.com'
}
})
Create Email Group
const emailGroup = await inbound.endpoints.create({
name: 'Dev Team',
type: 'email_group',
description: 'Forward to development team',
config: {
emails: [
'dev1@yourdomain.com',
'dev2@yourdomain.com',
'dev3@yourdomain.com'
]
}
})
Create Parameters
Unique name for the endpoint
Endpoint type: webhook
, email
, or email_group
Configuration specific to endpoint type
Webhook Config
HTTPS URL to receive webhooks
Request timeout in seconds (5-60)
Number of retry attempts (0-5)
Custom headers to send with webhooks
Get Endpoint Details
const endpoint = await inbound.endpoints.get('endp_abc123')
console.log('Endpoint:', endpoint.name)
console.log('Type:', endpoint.type)
console.log('Active:', endpoint.isActive)
console.log('Total deliveries:', endpoint.deliveryStats.total)
console.log('Success rate:',
(endpoint.deliveryStats.successful / endpoint.deliveryStats.total * 100).toFixed(2) + '%'
)
Update Endpoint
// Update webhook URL
const updated = await inbound.endpoints.update('endp_abc123', {
config: {
url: 'https://api.yourdomain.com/new-webhook',
timeout: 45,
retryAttempts: 5
}
})
// Disable endpoint
const disabled = await inbound.endpoints.update('endp_abc123', {
isActive: false
})
// Update description
const described = await inbound.endpoints.update('endp_abc123', {
description: 'Updated webhook for v2 API'
})
Update Parameters
New name for the endpoint
Enable or disable the endpoint
New configuration (replaces existing)
Delete Endpoint
const result = await inbound.endpoints.delete('endp_abc123')
console.log('Endpoint deleted')
console.log('Email addresses updated:', result.cleanup.emailAddressesUpdated)
console.log('Domains updated:', result.cleanup.domainsUpdated)
Deleting an endpoint will update all associated email addresses and domains to remove the routing. This action cannot be undone.
Practical Examples
Health Check Monitoring
async function checkEndpointHealth() {
const endpoints = await inbound.endpoints.list({ active: 'true' })
const unhealthy = endpoints.data.filter(endpoint => {
const { deliveryStats } = endpoint
if (deliveryStats.total === 0) return false
const successRate = deliveryStats.successful / deliveryStats.total
return successRate < 0.95 // Less than 95% success
})
if (unhealthy.length > 0) {
console.log('Unhealthy endpoints:', unhealthy.map(e => ({
name: e.name,
successRate: (e.deliveryStats.successful / e.deliveryStats.total * 100).toFixed(2) + '%',
failed: e.deliveryStats.failed
})))
}
}
Webhook with Authentication
// Create secure webhook
const secureWebhook = await inbound.endpoints.create({
name: 'Secure API Webhook',
type: 'webhook',
config: {
url: 'https://api.yourdomain.com/secure-webhook',
timeout: 30,
retryAttempts: 3,
headers: {
'Authorization': `Bearer ${process.env.WEBHOOK_SECRET}`,
'X-Webhook-Version': '1.0'
}
}
})
// Verify webhook in your handler
export async function POST(request: Request) {
const authHeader = request.headers.get('Authorization')
if (authHeader !== `Bearer ${process.env.WEBHOOK_SECRET}`) {
return new Response('Unauthorized', { status: 401 })
}
// Process webhook...
}
Dynamic Email Groups
async function createDepartmentGroup(
department: string,
emails: string[]
) {
// Validate email limit (max 50)
if (emails.length > 50) {
throw new Error('Email groups support maximum 50 addresses')
}
return await inbound.endpoints.create({
name: `${department} Team`,
type: 'email_group',
description: `Auto-forward to ${department} team members`,
config: {
emails: emails
}
})
}
// Update group members
async function updateGroupMembers(
endpointId: string,
newEmails: string[]
) {
return await inbound.endpoints.update(endpointId, {
config: {
emails: newEmails
}
})
}
Failover Configuration
// Create primary and backup endpoints
const primary = await inbound.endpoints.create({
name: 'Primary Webhook',
type: 'webhook',
config: {
url: 'https://api.primary.com/webhook',
timeout: 30,
retryAttempts: 2
}
})
const backup = await inbound.endpoints.create({
name: 'Backup Email Forward',
type: 'email',
config: {
email: 'backup@yourdomain.com'
}
})
// Monitor and switch if needed
async function checkAndSwitch(emailAddressId: string) {
const endpoint = await inbound.endpoints.get(primary.id)
const failureRate = endpoint.deliveryStats.failed / endpoint.deliveryStats.total
if (failureRate > 0.1) { // More than 10% failure
// Switch to backup
await inbound.emailAddresses.update(emailAddressId, {
endpointId: backup.id
})
// Notify admin
await notifyAdmin('Switched to backup endpoint due to high failure rate')
}
}
Endpoint Analytics
async function getEndpointAnalytics() {
const endpoints = await inbound.endpoints.list()
const analytics = endpoints.data.map(endpoint => ({
name: endpoint.name,
type: endpoint.type,
totalEmails: endpoint.deliveryStats.total,
successRate: endpoint.deliveryStats.total > 0
? (endpoint.deliveryStats.successful / endpoint.deliveryStats.total * 100).toFixed(2)
: 'N/A',
lastDelivery: endpoint.deliveryStats.lastDelivery,
isActive: endpoint.isActive,
emailCount: endpoint.type === 'email_group'
? endpoint.groupEmails?.length || 0
: 1
}))
return analytics
}
Best Practices
- Use descriptive names for endpoints to easily identify their purpose
- Set appropriate timeouts based on your webhook processing time
- Configure retry attempts to handle temporary failures
- Use webhook headers for authentication and versioning
- Monitor delivery statistics regularly
- Keep email groups under 50 addresses for optimal delivery
Next Steps