POST
/
api
/
v2
/
email-addresses
import { Inbound } from '@inboundemail/sdk'

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

const { data: emailAddress, error } = await inbound.email.address.create({
  address: 'hello@example.com',
  domainId: 'dom_abc123',
  endpointId: 'end_xyz789',
  isActive: true
})

if (error) {
  console.error('Failed to create email address:', error)
} else {
  console.log('Email address created:', emailAddress.id)
}

{
  "id": "email_addr_123",
  "address": "hello@example.com",
  "domainId": "dom_abc123",
  "webhookId": null,
  "endpointId": "end_xyz789",
  "isActive": true,
  "isReceiptRuleConfigured": true,
  "receiptRuleName": "example.com-individual-rule",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "userId": "user_123",
  "domain": {
    "id": "dom_abc123",
    "name": "example.com",
    "status": "verified"
  },
  "routing": {
    "type": "endpoint",
    "id": "end_xyz789",
    "name": "Main Endpoint",
    "config": {
      "type": "webhook",
      "url": "https://api.yourapp.com/webhooks/email"
    },
    "isActive": true
  }
}

​
Overview

This endpoint creates a new email address and automatically configures AWS SES receipt rules for email forwarding. You can route emails to either a webhook or an endpoint.
This endpoint does not require domain verification before creating email addresses. However, AWS SES receipt rules will only be configured if the domain is properly set up.

​
Authentication

​
Authorization
string
required
Bearer token for API authentication. Format: Bearer YOUR_API_KEY

​
Request Body

​
address
string
required
The email address to create (e.g., “hello@example.com”). Must be a valid email format and use a domain you own.
​
domainId
string
required
The ID of the verified domain this email address belongs to.
​
endpointId
string
ID of the endpoint to route emails to. Cannot be used together with webhookId.
​
webhookId
string
ID of the webhook to route emails to. Cannot be used together with endpointId.
​
isActive
boolean
default:"true"
Whether the email address should be active and able to receive emails.

​
Response

​
id
string
required
Unique identifier for the newly created email address.
​
address
string
required
The email address that was created.
​
domainId
string
required
ID of the domain this email address belongs to.
​
webhookId
string | null
ID of the webhook endpoint for routing emails (if using webhook routing).
​
endpointId
string | null
ID of the endpoint for routing emails (if using endpoint routing).
​
isActive
boolean
required
Whether this email address is active and can receive emails.
​
isReceiptRuleConfigured
boolean
required
Whether AWS SES receipt rule was successfully configured.
​
receiptRuleName
string | null
Name of the AWS SES receipt rule created for this email address.
​
createdAt
string
required
ISO 8601 timestamp when the email address was created.
​
updatedAt
string
required
ISO 8601 timestamp when the email address was last updated.
​
userId
string
required
ID of the user who owns this email address.
​
domain
object
required
Domain information for this email address.
​
routing
object
required
Email routing configuration.
​
warning
string
Warning message if there were issues with AWS SES configuration.

​
Examples

​
Create Email Address with Endpoint

import { Inbound } from '@inboundemail/sdk'

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

const { data: emailAddress, error } = await inbound.email.address.create({
  address: 'hello@example.com',
  domainId: 'dom_abc123',
  endpointId: 'end_xyz789',
  isActive: true
})

if (error) {
  console.error('Failed to create email address:', error)
} else {
  console.log('Email address created:', emailAddress.id)
}

​
Create Email Address with Webhook

import { Inbound } from '@inboundemail/sdk'

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

const { data: emailAddress, error } = await inbound.email.address.create({
  address: 'support@example.com',
  domainId: 'dom_abc123',
  webhookId: 'webhook_456',
  isActive: true
})

if (error) {
  console.error('Failed to create email address:', error)
} else {
  console.log('Email address created:', emailAddress.id)
}

​
Response

{
  "id": "email_addr_123",
  "address": "hello@example.com",
  "domainId": "dom_abc123",
  "webhookId": null,
  "endpointId": "end_xyz789",
  "isActive": true,
  "isReceiptRuleConfigured": true,
  "receiptRuleName": "example.com-individual-rule",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "userId": "user_123",
  "domain": {
    "id": "dom_abc123",
    "name": "example.com",
    "status": "verified"
  },
  "routing": {
    "type": "endpoint",
    "id": "end_xyz789",
    "name": "Main Endpoint",
    "config": {
      "type": "webhook",
      "url": "https://api.yourapp.com/webhooks/email"
    },
    "isActive": true
  }
}

​
Error Responses

{
  "error": "Missing required fields",
  "required": ["address", "domainId"]
}

​
Important Notes

Email addresses are automatically configured with AWS SES receipt rules upon creation when AWS is properly configured. This enables immediate email receiving capability.
The email address must belong to the specified domain. The API validates that the email domain matches the domain record.
Make sure your endpoint or webhook is active and properly configured before creating the email address to ensure emails are delivered successfully.

​
Email Routing Options

​
Endpoint Routing

Routes emails to a configured endpoint (webhook, email forwarding, etc.)
  • More flexible routing options
  • Can include additional configuration
  • Managed through the endpoints API

​
Webhook Routing

Routes emails directly to a webhook URL
  • Simple webhook-based routing
  • Direct HTTP POST to specified URL
  • Managed through the webhooks API

​
No Routing

Email addresses without routing will receive emails but won’t forward them anywhere
  • Useful for testing or temporary addresses
  • Emails are stored but not forwarded
After creating an email address, you might want to:
  • Update routing: Use PUT /api/v2/email-addresses/{id}
  • Check status: Use GET /api/v2/email-addresses/{id}
  • List all addresses: Use GET /api/v2/email-addresses

​
Notes

  • Email addresses can be created for any domain owned by the user
  • AWS SES receipt rules are automatically created and managed when AWS is configured
  • Email addresses can be created with or without routing configuration
  • The email address must belong to the specified domain (validated by domain matching)
  • Only one routing method (endpoint or webhook) can be used per email address
  • Domain verification is not required for email address creation, but proper AWS setup is needed for email receiving
Documentation Verified - This endpoint documentation has been verified against the actual API implementation (POST /api/v2/email-addresses) and is accurate as of the verification date.
1.0 - ✅