DOCSEARCHbyAlgolia
Submit Docs

EmailThing

repository·main·Indexed 43 days ago

https://github.com/riskymh/emailthing

A web application for receiving and sending emails that gives users control over their email infrastructure. It features a React-based PWA frontend, a Bun-based API (v0), a JavaScript SDK, and a CLI with an AI-driven 'Agent mode' for email automation. The system supports custom domains via Cloudflare Workers and provides endpoints for receiving emails, sending via mailbox aliases, and token authentication.

Tokens
20.1K
Snippets
73
Records
88
Agent score
55%

What's inside EmailThing

  1. EmailThing PWA technology stack

    main

    The EmailThing PWA is built using the following technologies:

    Custom Implementation Details:

    • Authentication: Uses a custom and simple hashing mechanism for passwords.

  2. EmailThing API v0 Overview

    main

    The EmailThing API (v0) allows you to receive emails from custom domains or Cloudflare email workers and send emails using mailbox aliases.

    Base URL: https://api.emailthing.app/api/v0/

    Note: This is currently in version 0 and may contain breaking changes.

    JS SDK: You can use the official JavaScript SDK available on npm: https://www.npmjs.com/package/emailthing.

  3. Overview of EmailThing architecture

    main

    EmailThing is a web application designed for receiving and sending emails. The project is split into two primary components:

    1. PWA (Frontend): A local-first React Single Page Application (SPA) built with React and the Bun bundler. It is designed to be hosted on Cloudflare Pages and serves as the user interface for managing emails.
    2. API (Backend): A Bun-based API built using Bun.serve. It is designed to be hosted on a VPS and handles the core logic for sending and receiving emails, as well as providing syncing APIs for the frontend.

    The PWA communicates with the API via API calls to manage the underlying database.

  4. EmailThing CLI Modes

    main

    The EmailThing CLI operates in two primary modes:

    1. Normal interactive: A terminal-based UI for navigating mailboxes, reading emails, and composing new messages manually.
    2. Agent mode: A command-driven mode intended for AI agents to automate email interactions via the CLI.

  5. Getting started with EmailThing

    main

    To use or deploy EmailThing, you need to interact with its two distinct applications. Depending on your goal (frontend UI vs. backend logic), refer to the specific application documentation:

    • For the Frontend (PWA): Use the documentation in apps/pwa for instructions on the React-based PWA.
    • For the Backend (API): Use the documentation in apps/api for instructions on the Bun-based API.

    Detailed self-hosting and contribution guides are located within those individual directories.

  6. Set up a Cloudflare Worker to receive emails

    main

    To receive emails for your custom domain using EmailThing, you must deploy a Cloudflare Worker and configure a route in your Cloudflare dashboard to point to it. This worker receives the email and sends the raw body to the EmailThing front-end application via the fetch API.

    Configuration

    Set the following environment variables in your Cloudflare Worker:

    • auth: Must match the value provided in your custom domain settings to authorize the request.
    • forward (optional): If provided, Cloudflare will forward the received email to the specified address.

    Self-Hosting with a Default Domain

    If you are self-hosting and want to use a default domain, you must append the following query parameters to your route:

    • zone: The domain you want to use (e.g., riskymh.dev).
    • internal: Set to 1.

    Note: This worker is the recommended method for handling custom domains, even if you are not self-hosting the main application.

  7. Install and run EmailThing CLI

    main

    EmailThing CLI is an interactive terminal email client that supports both a normal interactive mode and an AI agent mode for email automation.

    Prerequisite: This package requires Bun as its runtime.

    You can run the CLI directly using bunx.

    $ bunx @emailthing/cli

  8. Build the EmailThing PWA for production

    main

    To build the production version of the app, navigate to the apps/pwa directory and run the build command. This will generate the static HTML files in the dist directory.

    Note: This command must be executed within the pwa directory.

    # in pwa directory
bun build

  9. Install and initialize the EmailThing SDK

    main

    To use the EmailThing SDK, import the EmailThing class from the emailthing package. You must provide your API key, which can be retrieved from the EmailThing mailbox configuration page.

    Note: This project is currently in v0 and may contain breaking changes.

    import { EmailThing } from 'emailthing';
const emailthing = new EmailThing('et__aaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbb');

  12. Use EmailThing CLI Agent mode

    main

    The CLI includes an 'Agent mode' designed to let an AI agent interact with your emails via the command line. You can use the agent command to perform specific tasks like listing emails or retrieving specific email content.

    Available agent commands:

    • agent list: View your list of emails.
    • agent email <id>: View the content of a specific email using its ID.
    # See your email list
$ bunx @emailthing/cli agent list

# See a specific email by ID
$ bunx @emailthing/cli agent email id12345