DOCSEARCHbyAlgolia
Submit Docs

Inbound Email Infrastructure

repository·main·Indexed 43 days ago

https://github.com/inboundemail/inbound

Programmable email infrastructure for sending and receiving emails via an SDK, featuring automatic processing of incoming messages through webhooks. Includes a CDK stack for deploying AWS resources such as S3 buckets, Lambda functions, and SES Receipt Rule Sets.

Tokens
31.5K
Snippets
93
Records
140
Agent score
56%

What's inside Inbound

  1. What is Inbound?

    main

    Inbound is an email processing API designed for programmatic email management. It provides capabilities for:

    • Sending emails: Transactional email support using a Resend-compatible API.
    • Receiving emails: Real-time processing of incoming emails via webhooks.
    • Replying to emails: Full threading support to maintain conversation context.
    • Domain management: Tools to add and verify custom domains.

  2. Overview of Inbound Email capabilities with inbound.new

    main

    Inbound provides end-to-end email infrastructure designed for developers who need to receive and process emails programmatically. Unlike traditional 'send-only' platforms, Inbound is built for bidirectional email workflows, allowing you to send, receive, and reply to emails via API.

    Key features include:

    • Webhook-first design: Receive structured JSON events containing full message metadata (subject, body, sender, etc.).
    • Automated Parsing: Out-of-the-box MIME and attachment parsing.
    • Attachment Handling: Files are delivered with secure, signed URLs.
    • Reliability: Built-in retries, deduplication, and spam/abuse filtering.
    • Simplified Infrastructure: Managed MX and SPF configuration for easy domain setup.

  3. What is Inbound Guard?

    main
    Inbound Guard acts as a firewall for your inbox, sitting between the outside world and your emails. It evaluates every incoming message against user-defined rules before it reaches your inbox. It allows you to block, flag, or route emails based on specific criteria, providing a layer of intelligent filtering that goes beyond traditional spam filters.

  5. Best practices for webhook security

    main

    Follow these security guidelines when handling Inbound webhooks:

    • Always verify in production: Never skip verification in production environments to prevent unauthorized access.
    • Handle failures gracefully: When verification fails, log the attempt (including X-Endpoint-ID and timestamp) and return a 401 Unauthorized response.
    • Secure API Keys: Never hardcode INBOUND_API_KEY. Use environment variables or secrets management services and rotate them regularly.

  6. How Inbound works: Sending and Receiving

    main

    Inbound provides two primary capabilities: sending and receiving emails programmatically.

    Sending Emails

    You can send emails using the SDK or the API. The SDK is designed to be highly compatible with the Resend SDK, making migrations straightforward.

    Receiving Emails

    You can receive emails via endpoints. You have two main strategies for routing incoming mail:

    1. Specific Endpoints: Attach unique endpoints to individual email addresses (e.g., support@yourdomain.com).
    2. Catch-all Endpoints: Set up a catch-all for a domain so that any email not matching a specific address is routed to a fallback endpoint.

    Conceptual Routing Example:

    switch (email) {
  case 'support@yourdomain.com':
    endpoint1  // Specific endpoint for support
  case 'sales@yourdomain.com':
    endpoint2  // Specific endpoint for sales
  default:    // catch-all
    endpoint3  // Fallback endpoint for all other emails
}

  7. How mixed email routing works

    main

    Inbound supports a mixed mode routing pattern that allows you to configure both specific email addresses and a catch-all endpoint on the same domain simultaneously. This functions like a switch-case statement with a default fallback.

    Routing Priority

    The system resolves email destinations using the following precedence order:

    1. Specific email address endpoint (Highest priority)
    2. Legacy webhook for specific email (Backward compatibility)
    3. Catch-all endpoint (Fallback)
    4. Legacy catch-all webhook (Backward compatibility)

    This allows you to route known, important addresses (like support@yourdomain.com) to dedicated webhooks while sending all other unsolicited or unplanned emails to a single general-purpose endpoint.

    switch (email) {
  case 'support@yourdomain.com':
    webhook1  // Specific endpoint for support
  case 'sales@yourdomain.com':
    webhook2  // Specific endpoint for sales
  default:    // catch-all
    webhook3  // Fallback endpoint for all other emails
}

  8. Manage and select Mailbox Scopes

    main

    Inbound uses 'mailbox scopes' to partition email access. You can list all available scopes to see what you have access to. When performing actions, use the -m <name> flag to specify the target mailbox.

    Selectors like *@example.com can be used to include all recipients at a specific domain. Avoid broadening the scope of a mailbox without explicit confirmation.

    inboundctl mailbox list --json

  9. How @inboundemail/smtp-gateway works

    main

    The SMTP gateway acts as a standalone proxy that relays mail to the Inbound HTTP API.

    1. Authentication: Uses AUTH PLAIN or LOGIN over TLS. The username must be inbound and the password is your Inbound API key. The gateway performs a lightweight authenticated GET against the API to verify the key and caches successful keys in memory for 5 minutes.
    2. Data Processing: Raw MIME is parsed and mapped to the POST /api/e2/emails JSON format. This includes mapping headers (from/to/cc/bcc), body (html/text), reply-to, In-Reply-To/References, and converting attachments to base64. Each request is sent with the API key as a Bearer token and a content-derived Idempotency-Key.
    3. Error Mapping: SMTP responses are derived from API status codes:
      • 429 (Too Many Requests) $\rightarrow$ 451 (Local error, try again later)
      • 413 (Payload Too Large) $\rightarrow$ 552 (Requested mail action aborted: insufficient system storage)
      • Other 4xx $\rightarrow$ 550 (Requested action not taken: mailbox unavailable)
      • 5xx $\rightarrow$ 451 (Local error)

    All business logic, including domain ownership, blocklists, bans, and billing, is enforced by the API, not the gateway.

  10. Transition from DIY Mail Servers to Inbound API

    main

    Instead of maintaining a custom mail server, managing MX records, manually decoding multipart MIME, and building custom spam filters, you can use Inbound to receive emails as structured JSON via webhooks.

    Inbound provides:

    • Webhook-first delivery: Receives structured JSON containing subject, sender, body text, and attachments.
    • Simplified DNS: Automated MX and DKIM configuration.
    • Reliability: Built-in retries, deduplication, and handling of attachments/metadata.
    • Unified Workflow: A single API to send, receive, and reply to emails.

  11. Default Rate Limits for Inbound API

    main

    By default, the Inbound API enforces a rate limit of 100 requests per second per account. This budget is shared across all authenticated E2 API endpoints, including:

    • Email sending endpoints
    • Email management endpoints
    • Domain/configuration endpoints
    • All other authenticated E2 endpoints

    Note: Rate limits are applied per account. If you use multiple accounts, each account has its own independent rate limit bucket.

  12. Manage cache with hierarchical Query Keys

    main

    Use a hierarchical structure for query keys to enable precise cache management and invalidation. The recommended pattern is: [feature, type, ...identifiers].

    Examples:

    • ['analytics', 'data']
    • ['domains', 'stats']
    • ['domains', 'details', domainId]