DELETE
/
api
/
v2
/
email-addresses
/
{id}
import { InboundEmailClient } from '@inboundemail/sdk';

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.email.address.delete('email_addr_123');

if (error) {
  console.error('Error:', error);
} else {
  console.log('Email address deleted:', data);
}

{
  "message": "Email address deleted successfully",
  "cleanup": {
    "sesRuleUpdated": true,
    "emailAddress": "hello@example.com",
    "domain": "example.com"
  }
}

​
Overview

This endpoint permanently deletes an email address and automatically updates AWS SES receipt rules. If other email addresses exist on the same domain, the SES rules are updated to exclude the deleted address. If no other addresses exist, the entire SES rule is removed.
This action is irreversible. The email address and its configuration will be permanently deleted.

​
Authentication

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

​
Parameters

​
id
string
required
The unique identifier of the email address to delete.

​
Response

​
message
string
required
Success message confirming the deletion.
​
cleanup
object
required
Details about the cleanup operations performed.

​
Examples

​
Request

import { InboundEmailClient } from '@inboundemail/sdk';

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.email.address.delete('email_addr_123');

if (error) {
  console.error('Error:', error);
} else {
  console.log('Email address deleted:', data);
}

​
Response (SES Rule Updated)

{
  "message": "Email address deleted successfully",
  "cleanup": {
    "sesRuleUpdated": true,
    "emailAddress": "hello@example.com",
    "domain": "example.com"
  }
}

​
Response (SES Rule Removed)

{
  "message": "Email address deleted successfully", 
  "cleanup": {
    "sesRuleUpdated": true,
    "emailAddress": "last@example.com",
    "domain": "example.com"
  }
}

​
Response (With Warning)

{
  "message": "Email address deleted successfully",
  "cleanup": {
    "sesRuleUpdated": false,
    "emailAddress": "hello@example.com",
    "domain": "example.com",
    "warning": "AWS configuration incomplete. SES rules may need manual cleanup."
  }
}

​
Error Responses

{
  "error": "Email address not found"
}

​
Deletion Process

The email address deletion follows these steps:
1

Validate Ownership

Verify that the email address exists and belongs to the authenticated user.
2

Check Domain Context

Identify other active email addresses on the same domain to determine SES rule updates needed.
This ensures proper SES rule management for remaining email addresses.
3

Delete Email Address

Remove the email address record from the database.
This step is irreversible - the email address configuration is permanently lost.
4

Update SES Rules

Update AWS SES receipt rules based on remaining email addresses:
  • If other addresses exist: Update rule to exclude deleted address
  • If no addresses remain: Remove the entire SES rule for the domain
This ensures proper email routing for remaining addresses and cleanup when none remain.

​
SES Rule Management

​
Multiple Email Addresses on Domain

When other email addresses exist on the same domain:
  • The SES receipt rule is updated to remove the deleted address
  • Other email addresses continue to function normally
  • The domain’s SES configuration remains intact

​
Last Email Address on Domain

When deleting the last email address on a domain:
  • The entire SES receipt rule for the domain is removed
  • The domain can still receive catch-all emails if configured
  • Individual email routing for that domain stops completely

​
Important Notes

Email address deletion automatically manages AWS SES receipt rules to ensure proper email routing for remaining addresses.
Deleting an email address is permanent. The address cannot be recovered, though it can be recreated as a new address.
If you encounter SES cleanup warnings, the email address is still deleted from the database, but you may need to manually clean up AWS SES rules.

​
Impact on Email Delivery

​
Before Deletion

  • Emails to the address are received and forwarded according to routing configuration
  • SES receipt rules include this address in their configuration

​
After Deletion

  • Emails to the deleted address are no longer received
  • SES receipt rules are updated to exclude this address
  • Other email addresses on the domain continue to function normally

​
AWS SES Integration

The deletion process handles SES integration automatically:

​
Successful SES Updates

  • sesRuleUpdated: true indicates successful AWS SES cleanup
  • Email routing is properly updated for remaining addresses
  • No manual intervention required

​
Failed SES Updates

  • sesRuleUpdated: false with warning message
  • Email address still deleted from database
  • Manual SES rule cleanup may be required
  • Common causes: AWS configuration issues, permissions problems
Before deleting an email address, you might want to:
  • Check current configuration: GET /api/v2/email-addresses/{id}
  • Update routing temporarily: PUT /api/v2/email-addresses/{id}
  • List other addresses on domain: GET /api/v2/email-addresses?domainId={domainId}
After deletion, you can:
  • Recreate the address: POST /api/v2/email-addresses
  • Check domain status: GET /api/v2/domains/{domainId}
  • Review remaining addresses: GET /api/v2/email-addresses

​
Notes

  • Email address deletion affects AWS SES receipt rules automatically
  • Other email addresses on the same domain continue to function
  • The domain itself remains unaffected by individual email address deletion
  • Deleted email addresses can be recreated with the same address
  • SES rule management ensures no interruption to other email addresses on the domain

​
Verification Status

Documentation Verified: This endpoint documentation has been verified against the actual API implementation on January 25, 2025. The endpoint behavior, request/response formats, authentication methods, and SES integration details match the implementation in /api/v2/email-addresses/[id]/route.ts.
1.0 - ✅