inbox_beam 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37058947d959f74df792bb57612cc68eafe87a5eebcae8c9481fde1f1db31519
+  data.tar.gz: a7378b0b196ee61f516aab55869b66701180e3b84589d2c81aad4a8e09ea0761
+SHA512:
+  metadata.gz: 79eff3ed7f9c5d519d78125b15a09d859270891109bdd3211bdeabc28c8a78ee21939be7c1600294bc72407880af1a07bbf7cee3d3bafb3b0cd204fe5b3f5cb6
+  data.tar.gz: 979eafb2c9a9f402bd74720625bde4914a99737a395cc77786842bf764c1d2474126d15822a76ecfcabc4acdce7aae2b869c1ccdfcd18b3dac53e44fc090de7b

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- `InboxBeam::Client`: append messages to a mailbox via IMAP `APPEND` (stdlib `net/imap`), app-password or OAuth2 (XOAUTH2) auth.
+- `InboxBeam::Message`: dependency-free, UTF-8-safe RFC 5322 message builder (encoded-word headers, base64 bodies, `multipart/alternative` for html + text).
+- `InboxBeam::DeliveryMethod`: drop-in Action Mailer delivery method (`config.action_mailer.delivery_method = :inbox_beam`), auto-registered via Railtie.
+- Options: `mailbox`, `from`, `to`, `unread`, `subject_prefix`, per-call overrides.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toyoshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# inbox_beam
+
+[![Gem Version](https://img.shields.io/gem/v/inbox_beam.svg)](https://rubygems.org/gems/inbox_beam)
+[![license](https://img.shields.io/github/license/toyoshi/inbox_beam.svg)](./LICENSE)
+
+**Send notification emails to your own inbox from Ruby and Rails without SMTP, a sending domain, or SPF/DKIM/DMARC setup.**
+
+If all you want is for your Rails app to drop a contact-form copy, a sign-up
+alert, or a cron failure into *your own* inbox, configuring SMTP, a sending
+domain, SPF, DKIM, DMARC, and a provider like SES, SendGrid, or Postmark is a lot
+of deliverability overhead for mail only you will read.
+
+inbox_beam skips all of it. It uses the IMAP `APPEND` command to write the
+message straight into your mailbox. No SMTP, no sending domain, no
+deliverability — the email shows up unread and searchable, and nothing was sent.
+
+It ships as a plain Ruby client and as a drop-in **Action Mailer delivery
+method**, so your existing Rails mailers can land in your inbox unchanged.
+
+## Install
+
+```ruby
+# Gemfile
+gem "inbox_beam"
+```
+
+```sh
+bundle install
+# or
+gem install inbox_beam
+```
+
+Ruby >= 2.7.
+
+## Rails / Action Mailer
+
+Point Action Mailer at the `:inbox_beam` delivery method. Every mailer you
+already have now appends to your inbox instead of sending over SMTP:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :inbox_beam
+config.action_mailer.inbox_beam_settings = {
+  host: "imap.gmail.com",
+  auth: { user: "you@example.com", pass: ENV["IMAP_APP_PASSWORD"] },
+  mailbox: "INBOX"
+}
+```
+
+```ruby
+NotificationMailer.contact_form(submission).deliver_now
+# → appended to your inbox. No SMTP, no SPF/DKIM/DMARC.
+```
+
+The delivery method is registered automatically when Rails loads.
+
+## Plain Ruby
+
+```ruby
+require "inbox_beam"
+
+beam = InboxBeam::Client.new(
+  host: "imap.gmail.com",
+  auth: { user: "you@example.com", pass: ENV["IMAP_APP_PASSWORD"] }
+)
+
+beam.beam(subject: "New contact", text: "someone submitted the form")
+```
+
+HTML plus text produces a `multipart/alternative` message:
+
+```ruby
+beam.beam(
+  subject: "Weekly report",
+  text: "Signups: 42",
+  html: "<h1>Weekly report</h1><p>Signups: 42</p>"
+)
+```
+
+Override the target mailbox per call:
+
+```ruby
+beam.beam(subject: "Cron failed", text: "nightly-export exited 1", mailbox: "Alerts")
+```
+
+## This is not email delivery
+
+inbox_beam appends to a mailbox you already control. It does not send mail and
+cannot reach anyone else. To email a user or customer, use SMTP or a delivery
+API. It keeps no send log and the date is set by the client, so don't use it
+where an audit trail matters. It's for your own notifications.
+
+## Gmail setup
+
+1. Enable IMAP in Gmail settings.
+2. Turn on 2-Step Verification and create an [App Password](https://myaccount.google.com/apppasswords).
+3. Use it as `auth[:pass]`.
+
+Workspace admins can disable app passwords. In that case pass an OAuth2 token as
+`auth[:access_token]` instead of `pass` (the client authenticates with XOAUTH2).
+A dedicated `notify@` account that forwards to you is safer than your primary
+account's credentials on a server.
+
+## API
+
+### `InboxBeam::Client.new(...)`
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `host:` | — | IMAP host, e.g. `imap.gmail.com`. |
+| `auth:` | — | `{ user:, pass: }` (app password) or `{ user:, access_token: }` (OAuth2). |
+| `port:` | `993` | |
+| `ssl:` | `true` | Use TLS. |
+| `mailbox:` | `"INBOX"` | Target mailbox or label. |
+| `from:` | `auth[:user]` | Default From. |
+| `to:` | `auth[:user]` | Default To. |
+| `unread:` | `true` | Leave appended messages unread. |
+| `subject_prefix:` | `nil` | Prepended to every subject. |
+
+### `client.beam(...)`
+
+Keyword args: `subject:` (required), `text:`, `html:`, `from:`, `to:`,
+`mailbox:`, `unread:`, `date:`. Per-call values override the constructor
+defaults. Returns an `InboxBeam::Result` with `mailbox`, `uid`, and
+`uid_validity` (uid comes from the server's `APPENDUID` response).
+
+### `InboxBeam::Message.build(...)`
+
+The RFC 5322 builder is available on its own if you want the raw message without
+the IMAP connection. Zero dependencies, UTF-8 safe.
+
+```ruby
+raw = InboxBeam::Message.build(from: "a@x.com", to: "b@x.com", subject: "Hi", text: "Body")
+```
+
+## How it works
+
+IMAP's `APPEND` command (RFC 9051 §6.3.12) adds a message to the end of a
+mailbox. It's the same command mail clients use to save sent copies and drafts.
+inbox_beam builds an RFC 5322 message and appends it over a TLS IMAP connection
+using Ruby's standard `net/imap` — no runtime dependencies of its own.
+
+A TypeScript/Node version is at
+[inbox-beam](https://github.com/toyoshi/inbox-beam).
+
+## License
+
+MIT

data/lib/inbox_beam/client.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "net/imap"
+require_relative "message"
+
+module InboxBeam
+  Result = Struct.new(:mailbox, :uid, :uid_validity, keyword_init: true)
+
+  # Writes a message directly into your own mailbox using IMAP APPEND.
+  #
+  # This is NOT email delivery. Nothing is sent over SMTP and no message leaves
+  # for another server — it is appended straight into the target mailbox. Use it
+  # to land your own app notifications in your own inbox without SPF/DKIM/DMARC.
+  class Client
+    DEFAULT_PORT = 993
+    DEFAULT_MAILBOX = "INBOX"
+
+    # @param host [String] IMAP host, e.g. "imap.gmail.com"
+    # @param auth [Hash] { user:, pass: } for an app password, or
+    #   { user:, access_token: } for OAuth2 (XOAUTH2)
+    # @param port [Integer]
+    # @param ssl [Boolean] use TLS
+    # @param mailbox [String] target mailbox / label
+    # @param from [String, nil] default From (defaults to auth[:user])
+    # @param to [String, nil] default To (defaults to auth[:user])
+    # @param unread [Boolean] leave appended messages unread
+    # @param subject_prefix [String, nil] prepended to every subject
+    def initialize(host:, auth:, port: DEFAULT_PORT, ssl: true,
+                   mailbox: DEFAULT_MAILBOX, from: nil, to: nil,
+                   unread: true, subject_prefix: nil)
+      @host = host
+      @auth = auth
+      @port = port
+      @ssl = ssl
+      @mailbox = mailbox
+      @from = from
+      @to = to
+      @unread = unread
+      @subject_prefix = subject_prefix
+    end
+
+    # Append one message to the mailbox.
+    # @return [InboxBeam::Result]
+    def beam(subject:, text: nil, html: nil, from: nil, to: nil,
+             mailbox: nil, unread: nil, date: nil)
+      to ||= @to || @auth[:user]
+      from ||= @from || to
+      mailbox ||= @mailbox
+      unread = @unread if unread.nil?
+      subject = "#{@subject_prefix} #{subject}" if @subject_prefix
+
+      raw = Message.build(from: from, to: to, subject: subject, text: text, html: html, date: date)
+      append(mailbox, raw, unread: unread)
+    end
+
+    # Append an already-encoded RFC 5322 message (e.g. Mail::Message#encoded).
+    # @return [InboxBeam::Result]
+    def append(mailbox, raw, unread: true)
+      flags = unread ? [] : [:Seen]
+      response = with_connection { |imap| imap.append(mailbox, raw, flags, nil) }
+      uid_validity, uid = append_uid(response)
+      Result.new(mailbox: mailbox, uid: uid, uid_validity: uid_validity)
+    end
+
+    private
+
+    def with_connection
+      imap = Net::IMAP.new(@host, port: @port, ssl: @ssl)
+      begin
+        if @auth[:access_token]
+          imap.authenticate("XOAUTH2", @auth[:user], @auth[:access_token])
+        else
+          imap.login(@auth[:user], @auth[:pass])
+        end
+        yield imap
+      ensure
+        begin
+          imap.logout
+        rescue StandardError
+          nil
+        end
+        imap.disconnect
+      end
+    end
+
+    # Parse the APPENDUID response code: [APPENDUID <uidvalidity> <uid>].
+    def append_uid(response)
+      code = response&.data&.code
+      return [nil, nil] unless code && code.name == "APPENDUID"
+
+      uid_validity, uid = code.data.to_s.split(" ", 2)
+      [uid_validity&.to_i, uid&.to_i]
+    rescue StandardError
+      [nil, nil]
+    end
+  end
+end

data/lib/inbox_beam/delivery_method.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module InboxBeam
+  # Action Mailer delivery method. Instead of sending over SMTP, it appends the
+  # rendered message straight into your own mailbox via IMAP APPEND.
+  #
+  #   config.action_mailer.delivery_method = :inbox_beam
+  #   config.action_mailer.inbox_beam_settings = {
+  #     host: "imap.gmail.com",
+  #     auth: { user: "you@example.com", pass: ENV["IMAP_APP_PASSWORD"] },
+  #     mailbox: "INBOX"
+  #   }
+  #
+  # Existing mailers then land in your inbox with no sending domain, SPF, DKIM,
+  # or DMARC. For notifications you read yourself — not for mailing third parties.
+  class DeliveryMethod
+    attr_reader :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    # @param mail [Mail::Message]
+    def deliver!(mail)
+      opts = settings.dup
+      mailbox = opts.delete(:mailbox) || Client::DEFAULT_MAILBOX
+      unread = opts.key?(:unread) ? opts.delete(:unread) : true
+      Client.new(**opts).append(mailbox, mail.encoded, unread: unread)
+      mail
+    end
+  end
+end

data/lib/inbox_beam/message.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "base64"
+require "securerandom"
+
+module InboxBeam
+  # Builds an RFC 5322 message ready to hand to IMAP APPEND.
+  # Zero dependencies — UTF-8 safe via base64 bodies and encoded-word headers.
+  module Message
+    CRLF = "\r\n"
+
+    module_function
+
+    # @param from [String] e.g. "you@example.com" or "Name <you@example.com>"
+    # @param to [String]
+    # @param subject [String]
+    # @param text [String, nil]
+    # @param html [String, nil]
+    # @param date [Time, nil]
+    # @return [String] the raw RFC 5322 message with CRLF line endings
+    def build(from:, to:, subject:, text: nil, html: nil, date: nil)
+      date ||= Time.now
+      message_id = "<#{SecureRandom.hex(16)}@#{domain_of(from)}>"
+
+      headers = [
+        "From: #{encode_header(from)}",
+        "To: #{encode_header(to)}",
+        "Subject: #{encode_word(subject)}",
+        "Date: #{rfc2822_date(date)}",
+        "Message-ID: #{message_id}",
+        "MIME-Version: 1.0"
+      ]
+
+      if html && text
+        boundary = "inbox_beam_#{SecureRandom.hex(12)}"
+        headers << %(Content-Type: multipart/alternative; boundary="#{boundary}")
+        body = [
+          "--#{boundary}",
+          mime_part("text/plain", text),
+          "--#{boundary}",
+          mime_part("text/html", html),
+          "--#{boundary}--",
+          ""
+        ].join(CRLF)
+      elsif html
+        headers << "Content-Type: text/html; charset=UTF-8" << "Content-Transfer-Encoding: base64"
+        body = base64_body(html)
+      else
+        headers << "Content-Type: text/plain; charset=UTF-8" << "Content-Transfer-Encoding: base64"
+        body = base64_body(text.to_s)
+      end
+
+      raw = headers.join(CRLF) + CRLF + CRLF + body
+      raw.gsub(/\r\n|\r|\n/, CRLF)
+    end
+
+    def ascii?(value)
+      value.ascii_only?
+    end
+
+    # RFC 2047 encoded-word for non-ASCII header values.
+    def encode_word(value)
+      return value if ascii?(value)
+
+      "=?UTF-8?B?#{Base64.strict_encode64(value.encode("UTF-8"))}?="
+    end
+
+    # Encode a header that may contain a display name: `名前 <addr>`.
+    def encode_header(value)
+      return value if ascii?(value)
+
+      if (m = value.match(/\A(.*?)\s*<([^>]+)>\s*\z/))
+        "#{encode_word(m[1])} <#{m[2]}>"
+      else
+        encode_word(value)
+      end
+    end
+
+    # Base64-encode a body and wrap at 76 columns per RFC 2045.
+    def base64_body(content)
+      Base64.strict_encode64(content.encode("UTF-8")).scan(/.{1,76}/).join(CRLF)
+    end
+
+    def rfc2822_date(time)
+      time.getutc.strftime("%a, %d %b %Y %H:%M:%S +0000")
+    end
+
+    def domain_of(address)
+      m = address.match(/@([^>\s]+)/)
+      m ? m[1] : "localhost"
+    end
+
+    def mime_part(content_type, content)
+      [
+        "Content-Type: #{content_type}; charset=UTF-8",
+        "Content-Transfer-Encoding: base64",
+        "",
+        base64_body(content)
+      ].join(CRLF)
+    end
+  end
+end

data/lib/inbox_beam/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "delivery_method"
+
+module InboxBeam
+  # Registers the :inbox_beam Action Mailer delivery method when Rails is loaded.
+  class Railtie < Rails::Railtie
+    initializer "inbox_beam.add_delivery_method" do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method(:inbox_beam, InboxBeam::DeliveryMethod)
+      end
+    end
+  end
+end

data/lib/inbox_beam/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module InboxBeam
+  VERSION = "0.1.0"
+end

data/lib/inbox_beam.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "inbox_beam/version"
+require_relative "inbox_beam/message"
+require_relative "inbox_beam/client"
+require_relative "inbox_beam/delivery_method"
+
+# InboxBeam puts notifications into your own mailbox via IMAP APPEND —
+# no SMTP, no sending domain, no SPF/DKIM/DMARC.
+module InboxBeam
+end
+
+# Load the Action Mailer integration only when Rails is present.
+require_relative "inbox_beam/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: inbox_beam
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- toyoshi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-imap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: InboxBeam appends a message straight into your own mailbox using the
+  IMAP APPEND command instead of sending email. Useful for landing app notifications,
+  contact-form copies, and cron alerts in your own inbox without standing up a sending
+  domain. Includes a drop-in Action Mailer delivery method.
+email:
+- toyoshi@tokuiten.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/inbox_beam.rb
+- lib/inbox_beam/client.rb
+- lib/inbox_beam/delivery_method.rb
+- lib/inbox_beam/message.rb
+- lib/inbox_beam/railtie.rb
+- lib/inbox_beam/version.rb
+homepage: https://github.com/toyoshi/inbox_beam
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/toyoshi/inbox_beam
+  source_code_uri: https://github.com/toyoshi/inbox_beam
+  changelog_uri: https://github.com/toyoshi/inbox_beam/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Put notifications into your own mailbox via IMAP APPEND — no SMTP, no SPF/DKIM/DMARC.
+test_files: []