Wraps Logo
DocsHome
Inbound Email Quickstart

Receive Emails with Wraps

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:

Prerequisites

Before you begin, make sure you have:

  • Email infrastructure deployed (Email Quickstart)
  • A verified domain in AWS SES
  • AWS CLI installed with valid credentials

1
Deploy Inbound Infrastructure

Run the Wraps CLI to deploy inbound email infrastructure:

GNU Bashterminal.sh
npx @wraps.dev/cli email inbound init

What gets deployed?

  • S3 bucket for storing incoming emails
  • SES receipt rule set with active rule
  • Lambda function to parse and process emails
  • EventBridge for real-time email.received events
  • MX records configuration for your domain

2
Configure DNS (MX Record)

Add an MX record to your domain to route incoming emails to AWS SES. The CLI will display the exact record to add:

DNS Record
Type: MXName: @ (or your subdomain, e.g., inbound)Value: 10 inbound-smtp.us-east-1.amazonaws.comTTL: 300

Region-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).

3
Install the SDK

Install the @wraps.dev/email package (v0.6.0+):

npm install @wraps.dev/email

4
Read Inbound Emails

Use the SDK to list and read incoming emails:

TypeScriptlist-emails.ts
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:

TypeScriptget-email.ts
// 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);

5
Reply and Forward Emails

Reply to inbound emails with proper threading (In-Reply-To and References headers):

TypeScriptreply.ts
// 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:

TypeScriptforward.ts
// 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);

6
View in Dashboard

Run the dashboard to view inbound emails in a web interface:

GNU Bashterminal.sh
npx @wraps.dev/cli dashboard

Navigate to the Receiving tab to see all inbound emails with sender, subject, attachments, and spam/virus verdicts.

7
Listen to EventBridge Events

Every inbound email triggers an EventBridge event that you can use to build automated workflows, notifications, or integrations.

Event Details
Source:wraps.inbound
Detail Type:email.received
Detail:Full parsed email with headers, body, attachments, and spam/virus verdicts

envelopeRecipients 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

JSONevent.json
// 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

TypeScripthandler.ts
// 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

  • Create support tickets from customer emails
  • Send Slack/Teams notifications for new emails
  • Auto-respond to specific email patterns
  • Route emails to different teams based on recipient
  • Trigger workflows for order confirmations or invoices

Next Steps

Email SDK Reference

Full API reference for inbox methods, attachments, and email parsing.

View SDK Docs
CLI Commands

Manage inbound infrastructure with CLI commands.

View CLI Docs

Need Help?

If you run into any issues, check our GitHub discussions or open an issue.

Get Help