Inbound Email Quickstart
Set up inbound email receiving with AWS SES in under 5 minutes. Parse incoming emails, extract attachments, and build automated workflows.
Set up inbound email receiving in your AWS account. Parse incoming emails, extract attachments, reply with proper threading, and forward to your team.
Run this quickstart with your AI agent
Paste into Claude Code, Cursor, or any agent with shell access.
Using Claude Code? Install the Wraps skills for deeper context:
Before you begin, make sure you have:
Run the Wraps CLI to deploy inbound email infrastructure:
npx @wraps.dev/cli email inbound initWhat gets deployed?
Add an MX record to your domain to route incoming emails to AWS SES. The CLI will display the exact record to add:
Type: MXName: @ (or your subdomain, e.g., inbound)Value: 10 inbound-smtp.us-east-1.amazonaws.comTTL: 300Region-specific endpoint
The MX record endpoint varies by region. Use inbound-smtp.{region}.amazonaws.com where region is your SES region (e.g., us-east-1, eu-west-1).
Install the @wraps.dev/email package (v0.6.0+):
npm install @wraps.dev/email
Use the SDK to list and read incoming emails:
import { WrapsEmail } from '@wraps.dev/email';const email = new WrapsEmail({ inboxBucketName: 'your-inbound-bucket-name',});// List recent inbound emailsconst { emails, nextToken } = await email.inbox.list({ maxResults: 20,});for (const summary of emails) { console.log(`From: ${summary.emailId}`); console.log(`Key: ${summary.key}`); console.log(`Received: ${summary.lastModified}`);}Get full details for a specific email:
// Get full email detailsconst inboundEmail = await email.inbox.get('email-abc123');console.log('From:', inboundEmail.from.address);console.log('Subject:', inboundEmail.subject);console.log('Body:', inboundEmail.html || inboundEmail.text);// Check attachmentsif (inboundEmail.attachments.length > 0) { for (const att of inboundEmail.attachments) { console.log(`Attachment: ${att.filename} (${att.size} bytes)`); }}// Check spam/virus verdictsconsole.log('Spam:', inboundEmail.spamVerdict);console.log('Virus:', inboundEmail.virusVerdict);Reply to inbound emails with proper threading (In-Reply-To and References headers):
// Reply to an inbound email with proper threadingconst result = await email.inbox.reply('email-abc123', { from: 'support@yourdomain.com', text: 'Thanks for reaching out! We will get back to you shortly.', html: '<p>Thanks for reaching out! We will get back to you shortly.</p>',});console.log('Reply sent:', result.messageId);Forward emails to another address:
// Forward an inbound email to another recipientconst result = await email.inbox.forward('email-abc123', { from: 'noreply@yourdomain.com', to: 'team@yourdomain.com', addPrefix: '[Customer Email]',});console.log('Forwarded:', result.messageId);Run the dashboard to view inbound emails in a web interface:
npx @wraps.dev/cli dashboardNavigate to the Receiving tab to see all inbound emails with sender, subject, attachments, and spam/virus verdicts.
Every inbound email triggers an EventBridge event that you can use to build automated workflows, notifications, or integrations.
wraps.inboundemail.receivedenvelopeRecipients lists the addresses SES delivered to, limited to addresses this deployment receives for. It can differ from to. Use it to route on Bcc recipients, forwards and aliases. It is absent on mail received before wraps email upgrade. In a trimmed event from, to, cc and attachments can be empty or missing: read the full parsed email at parsedS3Key, or guard with ?? []. Events are delivered at least once, so deduplicate on emailId.
Event Payload Example
// EventBridge event payload (email.received){ "source": "wraps.inbound", "detail-type": "email.received", "detail": { "emailId": "abc123...", "messageId": "<message-id@mail.example.com>", "from": { "name": "John Doe", "address": "john@example.com" }, "to": [{ "name": "", "address": "support@yourdomain.com" }], "envelopeRecipients": ["support@yourdomain.com"], "subject": "Help with my order", "html": "<p>Email body...</p>", "text": "Email body...", "receivedAt": "2024-02-01T00:00:00.000Z", "spamVerdict": "PASS", "virusVerdict": "PASS", "attachments": [ { "id": "att-1", "filename": "screenshot.png", "size": 12345 } ], "replyToken": { "conversationId": "aGVsbG8gd29y", "sendId": "MDEyMzQ1Njc", "status": "valid" }, "autoReply": false }}Filter event.detail.replyToken?.status === "valid" to thread replies. See the reply-threading guide.
Very large emails are trimmed to fit the EventBridge size limit: the event then has truncated: true, drops html, text, headers or attachments (listed in truncatedFields), and gives the full parsed email's S3 key in parsedS3Key. Sender, recipients, subject and verdicts are kept unless they alone are too large; then to/cc are replaced by counts and the subject is cut, and as a last resort only emailId, rawS3Key, parsedS3Key, receivedAt, replyToken and autoReply are sent.
Example Lambda Handler
// Example: Lambda handler for email.received eventsexport async function handler(event: EventBridgeEvent) { const email = event.detail; console.log('New email from:', email.from?.address); console.log('Subject:', email.subject); // Route on who SES delivered to (covers Bcc and forwards). // Mail from before the upgrade has no envelopeRecipients. // A trimmed event can lack from/to/cc: read parsedS3Key for the full email. const recipients = email.envelopeRecipients ?? (email.to ?? []).map((t) => t.address.toLowerCase()); if (recipients.some(r => r.startsWith('support@'))) { await createSupportTicket(email); } else if (recipients.some(r => r.startsWith('orders@'))) { await processOrderEmail(email); }}Common Use Cases
Full API reference for inbox methods, attachments, and email parsing.
View SDK DocsManage inbound infrastructure with CLI commands.
View CLI Docs