sendio 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b82f47130797ce62b2a01860ba0b682f084aad772203c5e82085fe6b3f4ecf3
+  data.tar.gz: bb2edfd4bd16576f826c46f48d5745a60481b321609e2cec6338c4aafa9c9bab
+SHA512:
+  metadata.gz: aaaf1d140cdf58e068bc5b21d54865e202afbaee0921361c30d686faa8c8d5f72217b0dfd499679e0036e33cea5f100ecfb6f620d28a612894d2fb5e8e073769
+  data.tar.gz: cfca683fc0f253d84325d0319d76c86c0a3e077548ce35619bfbe3c56f26571d3ef2993ff493b581a2ee06f97401028159d32def6e8a750395e6b8345b38b031

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-11-11
+
+First public release.
+
+### Removed
+
+- `Sendio::Domains::Claims` (`.create`, `.get`, `.verify`): the API has no domain-claim routes, so every call failed with a 404. Claim a domain by deleting it from the team that owns it, then adding it to yours.
+
+### Added
+
+- `Sendio::Automations::Templates.list` (optional `category:` filter) and `.get(slug)` to browse the automation template catalog, and `Sendio::Automations.create_from_template(params, options: { idempotency_key: })` to create a disabled automation from a template.
+- `Sendio::Mailboxes` with `.list`, `.create`, `.update`, `.reset_password` and `.remove`, to manage mailboxes (email accounts with an IMAP/SMTP login).
+- `Sendio::Broadcasts.estimate`, `.test`, `.stats`, `.list_versions`, `.get_version`, `.update_version` and `.restore_version`.
+- Documented `capabilities: { receiving: "enabled" | "disabled" }` on `Sendio::Domains.create` and `Sendio::Domains.update` to turn email receiving on or off for a domain (turning it on asks for the domain's MX record, publish it to start receiving email; sending can't be disabled).
+- Documented the full set of broadcast create/update fields (`segment_ids`, `exclude_segment_ids`, `audience`, `unsubscribe_scope`, `tracking`, `template_engine`, `topic_id`, `preview_text`) and the `status`, `segment_id` and `search` list filters.
+
+### Fixed
+
+- `Sendio::Broadcasts.update` and `.send` no longer send `broadcast_id` in the JSON body; it goes only in the path (the API rejects any key but `name` when updating a sent broadcast).
+
+### Added
+
+- First release of the official send.io Ruby SDK (`sendio` gem).
+- Default API base URL `https://api.send.io`, overridable with `SENDIO_BASE_URL` or `Sendio.base_url = "..."` at runtime (trailing slash optional).

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Derich Pacheco and Resend
+Copyright (c) 2026 send.io
+
+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/NOTICE

@@ -0,0 +1 @@
+This SDK is based on https://github.com/resend/resend-ruby (MIT License), Copyright (c) Resend.

data/README.md

@@ -0,0 +1,210 @@
+# send.io Ruby and Rails SDK
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Gem Version](https://badge.fury.io/rb/sendio.svg)](https://badge.fury.io/rb/sendio)
+
+The official Ruby and Rails SDK for the [send.io](https://send.io) email API. Full API reference: <https://developer.send.io/docs/api>.
+
+## Installation
+
+Via RubyGems:
+
+```sh
+gem install sendio
+```
+
+Via Gemfile:
+
+```ruby
+gem "sendio"
+```
+
+Requires Ruby 3.2 or newer.
+
+## Quick start
+
+Create an API key in the send.io dashboard (keys start with `mx_`), then:
+
+```ruby
+require "sendio"
+
+Sendio.api_key = ENV["SENDIO_API_KEY"]
+
+email = Sendio::Emails.send({
+  from: "Acme <onboarding@yourdomain.com>",
+  to: ["delivered@send.io"],
+  subject: "Hello from send.io",
+  html: "<strong>It works!</strong>"
+})
+
+puts email[:id]
+```
+
+## Send a batch
+
+Up to 100 emails in one request:
+
+```ruby
+Sendio::Batch.send([
+  {
+    from: "Acme <onboarding@yourdomain.com>",
+    to: ["delivered@send.io"],
+    subject: "First",
+    html: "<p>one</p>"
+  },
+  {
+    from: "Acme <onboarding@yourdomain.com>",
+    to: ["delivered@send.io"],
+    subject: "Second",
+    html: "<p>two</p>"
+  }
+])
+```
+
+## Retrieve an email
+
+```ruby
+email = Sendio::Emails.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
+puts email[:last_event]
+
+Sendio::Emails.list(limit: 10)
+```
+
+## Domains
+
+```ruby
+domain = Sendio::Domains.create({ name: "yourdomain.com" })
+Sendio::Domains.verify(domain[:id])
+Sendio::Domains.get(domain[:id])
+Sendio::Domains.list
+Sendio::Domains.remove(domain[:id])
+
+# Receive email on the domain too (send.io then requires its MX record)
+domain = Sendio::Domains.create({ name: "yourdomain.com", capabilities: { receiving: "enabled" } })
+
+# Stop receiving: send.io stops accepting email for the domain; remove its MX record
+Sendio::Domains.update({ id: domain[:id], capabilities: { receiving: "disabled" } })
+
+# Turn it back on (asks for the domain's MX record; publish it to start receiving email)
+Sendio::Domains.update({ id: domain[:id], capabilities: { receiving: "enabled" } })
+```
+
+## Mailboxes
+
+Mailboxes are real email accounts with an IMAP/SMTP login. The domain must be verified.
+
+```ruby
+mailbox = Sendio::Mailboxes.create({ address: "support@yourdomain.com" })
+puts mailbox[:credentials] # shown once; the password is also an API key for this mailbox
+
+Sendio::Mailboxes.list
+Sendio::Mailboxes.update({ mailbox_id: mailbox[:id], warmup_enabled: false })
+Sendio::Mailboxes.reset_password(mailbox[:id]) # the old password stops working
+Sendio::Mailboxes.remove(mailbox[:id])         # also removes an agent inbox on it
+```
+
+Sending is always on; `capabilities: { sending: "disabled" }` is rejected with a 422.
+
+The SDK also covers API keys, segments, contacts, contact properties, topics, broadcasts, templates, webhooks, received emails, logs, suppressions and more. See the [examples folder](examples/) for one script per resource.
+
+## Configuration
+
+### API key
+
+```ruby
+Sendio.api_key = ENV["SENDIO_API_KEY"]
+
+# or
+Sendio.configure do |config|
+  config.api_key = ENV["SENDIO_API_KEY"]
+end
+
+# or lazily, evaluated on every request
+Sendio.api_key = -> { Current.user.sendio_api_key }
+```
+
+### Base URL
+
+Requests go to `https://api.send.io` by default. Override it (for testing or a different environment) with the `SENDIO_BASE_URL` environment variable or at runtime. A trailing slash is optional:
+
+```ruby
+# environment: SENDIO_BASE_URL=https://api.example.test
+Sendio.base_url = "https://api.example.test"
+Sendio.base_url = nil # back to SENDIO_BASE_URL or the default
+```
+
+## Error handling
+
+Non-2xx responses raise a subclass of `Sendio::Error`:
+
+```ruby
+begin
+  Sendio::Emails.send({ from: "bad", to: ["delivered@send.io"], subject: "x", html: "x" })
+rescue Sendio::Error::RateLimitExceededError => e
+  sleep e.retry_after.to_i
+rescue Sendio::Error::InvalidRequestError, Sendio::Error::NotFoundError => e
+  warn "request rejected: #{e.message}"
+rescue Sendio::Error => e
+  warn "send.io error: #{e.message}"
+end
+```
+
+## Rails and ActionMailer
+
+Use send.io as an ActionMailer delivery method in `config/environments/production.rb`:
+
+```ruby
+config.action_mailer.delivery_method = :sendio
+```
+
+Set your API key in an initializer:
+
+```ruby
+# config/initializers/sendio.rb
+Sendio.api_key = ENV["SENDIO_API_KEY"]
+```
+
+Then deliver as usual:
+
+```ruby
+class UserMailer < ApplicationMailer
+  default from: "Acme <onboarding@yourdomain.com>"
+
+  def welcome_email
+    @user = params[:user]
+    mail(to: ["delivered@send.io"], subject: "Welcome")
+  end
+end
+
+UserMailer.with(user: user).welcome_email.deliver_now!
+```
+
+## Rails and Action Mailbox
+
+The gem ships an Action Mailbox ingress so you can receive inbound email through send.io:
+
+```ruby
+# config/environments/production.rb
+config.action_mailbox.ingress = :sendio
+```
+
+Create a webhook (in the dashboard or with `Sendio::Webhooks.create`) subscribed to `email.received` and pointed at:
+
+```
+https://example.com/rails/action_mailbox/sendio/inbound_emails
+```
+
+Store the webhook signing secret (`whsec_...`) under `action_mailbox.sendio_signing_secret` in your Rails credentials, or in the `SENDIO_INGRESS_SIGNING_SECRET` environment variable. Each verified webhook is turned back into the full email and routed like any other ingress.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+`examples/smoke.rb` is a live check against a real API (sends one email). It needs `SENDIO_API_KEY` and, optionally, `SENDIO_BASE_URL`.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

data/app/controllers/action_mailbox/ingresses/sendio/inbound_emails_controller.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  module Ingresses
+    module Sendio
+      # Ingests inbound emails delivered by send.io's +email.received+ webhook.
+      #
+      # send.io webhooks only carry the received email's metadata, so the full message
+      # (including any attachments) is fetched from the send.io API before being enqueued
+      # for routing. The webhook request is authenticated by verifying its Svix signature
+      # against the webhook's signing secret, which is stored in the
+      # +action_mailbox.sendio_signing_secret+ Rails credential or the
+      # +SENDIO_INGRESS_SIGNING_SECRET+ environment variable.
+      #
+      # Returns:
+      #
+      # - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for
+      #   routing, or if the event is not an +email.received+ event and was ignored
+      # - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+      # - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails
+      #   from Sendio
+      # - <tt>422 Unprocessable Entity</tt> if the request's payload is malformed
+      # - <tt>500 Server Error</tt> if the webhook signing secret is missing, the send.io API
+      #   could not be reached, or one of the Active Record database, the Active Storage
+      #   service, or the Active Job backend is misconfigured or unavailable
+      class InboundEmailsController < ActionMailbox::BaseController
+        before_action :authenticate
+
+        def create
+          return head :no_content unless email_received_event?
+          return head :unprocessable_entity if email_id.nil?
+
+          ActionMailbox::InboundEmail.create_and_extract_message_id! raw_email
+          head :no_content
+        rescue JSON::ParserError => e
+          logger.error e.message
+          head :unprocessable_entity
+        end
+
+        private
+
+        def raw_email
+          ::Sendio::ActionMailbox::MessageBuilder.new(email_id).raw_email
+        end
+
+        def email_received_event?
+          event["type"] == "email.received"
+        end
+
+        def email_id
+          event.dig("data", "email_id")
+        end
+
+        def event
+          @event ||= JSON.parse(request.raw_post)
+        end
+
+        def authenticate
+          head :unauthorized unless authenticated?
+        end
+
+        def authenticated?
+          if signing_secret.present?
+            verified_signature?
+          else
+            raise ArgumentError, <<~MESSAGE.squish
+              Missing required Sendio webhook signing secret. Set action_mailbox.sendio_signing_secret
+              in your application's encrypted credentials or provide the SENDIO_INGRESS_SIGNING_SECRET
+              environment variable.
+            MESSAGE
+          end
+        end
+
+        def verified_signature?
+          ::Sendio::Webhooks.verify(
+            payload: request.raw_post,
+            headers: {
+              svix_id: request.headers["svix-id"],
+              svix_timestamp: request.headers["svix-timestamp"],
+              svix_signature: request.headers["svix-signature"]
+            },
+            webhook_secret: signing_secret
+          )
+        rescue RuntimeError
+          false
+        end
+
+        def signing_secret
+          Rails.application.credentials.dig(:action_mailbox, :sendio_signing_secret) ||
+            ENV["SENDIO_INGRESS_SIGNING_SECRET"]
+        end
+      end
+    end
+  end
+end

data/lib/sendio/action_mailbox/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Sendio
+  module ActionMailbox
+    # Rails engine that routes send.io's +email.received+ webhooks to the
+    # Action Mailbox ingress controller.
+    class Engine < ::Rails::Engine
+      initializer "sendio.action_mailbox.routes" do |app|
+        app.routes.append do
+          post "/rails/action_mailbox/sendio/inbound_emails",
+               to: "action_mailbox/ingresses/sendio/inbound_emails#create",
+               as: :rails_sendio_inbound_emails
+        end
+      end
+    end
+  end
+end

data/lib/sendio/action_mailbox/message_builder.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "mail"
+
+module Sendio
+  module ActionMailbox
+    # Rebuilds the full RFC 822 source of a received email so it can be ingested
+    # by Action Mailbox.
+    #
+    # send.io's +email.received+ webhook only carries metadata, so the message is
+    # fetched from the Received Emails API. When the API exposes a raw message
+    # download it is used as-is; otherwise the message is reconstructed as a
+    # Mail::Message from its parts, downloading each attachment through the
+    # attachments API.
+    class MessageBuilder
+      # Headers that describe the reconstructed MIME structure and therefore
+      # cannot be copied verbatim from the original message.
+      STRUCTURAL_HEADERS = %w[content-type content-transfer-encoding mime-version].freeze
+
+      # Envelope fields that are set from the API response when the original
+      # header of the same name is not available.
+      ENVELOPE_FIELDS = %i[from to cc bcc reply_to subject message_id].freeze
+
+      # @param email_id [String] The ID of the received email
+      def initialize(email_id)
+        @email_id = email_id
+      end
+
+      # @return [String] the full RFC 822 source of the received email
+      def raw_email
+        raw_download || rebuild_message.to_s
+      end
+
+      private
+
+      def email
+        @email ||= Sendio::Emails::Receiving.get(@email_id, html_format: "cid")
+      end
+
+      def raw_download
+        url = fetch(email[:raw], "download_url") unless blank?(email[:raw])
+        download(url) unless blank?(url)
+      end
+
+      def rebuild_message
+        Mail.new.tap do |mail|
+          copy_headers(mail)
+          copy_envelope(mail)
+          add_bodies(mail)
+          add_attachments(mail)
+        end
+      end
+
+      def copy_headers(mail)
+        (email[:headers] || {}).each do |name, value|
+          next if STRUCTURAL_HEADERS.include?(name.to_s.downcase)
+
+          Array(value).each { |val| mail.header[name.to_s] = val }
+        end
+      end
+
+      def copy_envelope(mail)
+        ENVELOPE_FIELDS.each do |field|
+          value = email[field]
+          next if blank?(value) || mail.header[field.to_s.tr("_", "-")]
+
+          mail.public_send("#{field}=", value)
+        end
+
+        mail.date ||= email[:created_at]
+
+        expose_bcc(mail)
+        copy_received_for(mail)
+      end
+
+      # Mail omits Bcc when serializing a message by default, but Action Mailbox
+      # needs it to route the email.
+      def expose_bcc(mail)
+        bcc = mail.header["bcc"]
+        bcc.include_in_headers = true if bcc.respond_to?(:include_in_headers)
+      end
+
+      # Preserve the addresses this email was received for (e.g. through a
+      # forwarding rule) so Action Mailbox can route on them.
+      def copy_received_for(mail)
+        Array(email[:received_for]).each { |address| mail.header["X-Original-To"] = address }
+      end
+
+      def add_bodies(mail)
+        html = presence(email[:html])
+        text = presence(email[:text])
+
+        if html
+          mail.text_part = build_part("text/plain", text) if text
+          mail.html_part = build_part("text/html", html)
+        elsif text
+          mail.content_type "text/plain; charset=UTF-8"
+          mail.body text
+        end
+      end
+
+      def build_part(mime_type, content)
+        Mail::Part.new(content_type: "#{mime_type}; charset=UTF-8", body: content)
+      end
+
+      def add_attachments(mail)
+        Array(email[:attachments]).each { |meta| add_attachment(mail, meta) }
+      end
+
+      def add_attachment(mail, meta)
+        details = Sendio::Emails::Receiving::Attachments.get(email_id: @email_id, id: fetch(meta, "id"))
+        filename = fetch(meta, "filename") || details[:filename]
+
+        mail.attachments[filename] = {
+          mime_type: fetch(meta, "content_type") || details[:content_type],
+          content: download(details[:download_url])
+        }
+
+        decorate_attachment(mail.attachments.last, meta)
+      end
+
+      def decorate_attachment(part, meta)
+        content_id = fetch(meta, "content_id")
+        part.content_id = normalize_content_id(content_id) unless blank?(content_id)
+
+        return unless fetch(meta, "content_disposition") == "inline"
+
+        part.content_disposition = "inline; filename=\"#{part.filename}\""
+      end
+
+      def normalize_content_id(content_id)
+        content_id.start_with?("<") ? content_id : "<#{content_id}>"
+      end
+
+      def download(url)
+        response = HTTParty.get(url)
+
+        unless response.code == 200
+          raise Sendio::Error::ServerError.new(
+            "Failed to download received email content (HTTP #{response.code})", response.code
+          )
+        end
+
+        response.body
+      end
+
+      # Nested objects come back from the API with string keys, but hand-built
+      # hashes (tests, console usage) often use symbols. Accept both.
+      def fetch(hash, key)
+        hash[key] || hash[key.to_sym]
+      end
+
+      def presence(value)
+        value unless blank?(value)
+      end
+
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+    end
+  end
+end

data/lib/sendio/action_mailbox.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "sendio"
+require "sendio/action_mailbox/message_builder"
+require "sendio/action_mailbox/engine" if defined?(::Rails::Engine)

data/lib/sendio/api_keys.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sendio
+  # api keys api wrapper
+  module ApiKeys
+    class << self
+      # https://developer.send.io/docs/api
+      def create(params)
+        path = "api-keys"
+        Sendio::Request.new(path, params, "post").perform
+      end
+
+      # https://developer.send.io/docs/api
+      def list(params = {})
+        path = Sendio::PaginationHelper.build_paginated_path("api-keys", params)
+        Sendio::Request.new(path, {}, "get").perform
+      end
+
+      # https://developer.send.io/docs/api
+      def remove(api_key_id = "")
+        path = "api-keys/#{api_key_id}"
+        Sendio::Request.new(path, {}, "delete").perform
+      end
+
+      # https://developer.send.io/docs/api
+      def update(params)
+        path = "api-keys/#{params[:id]}"
+        Sendio::Request.new(path, { name: params[:name] }, "patch").perform
+      end
+    end
+  end
+end

data/lib/sendio/automations/runs.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Sendio
+  module Automations
+    # Automation Runs api wrapper
+    module Runs
+      class << self
+        # https://developer.send.io/docs/api
+        def list(automation_id, params = {})
+          base_path = "automations/#{automation_id}/runs"
+          path = Sendio::PaginationHelper.build_paginated_path(base_path, params)
+          Sendio::Request.new(path, {}, "get").perform
+        end
+
+        # https://developer.send.io/docs/api
+        def get(automation_id, run_id)
+          Sendio::Request.new("automations/#{automation_id}/runs/#{run_id}", {}, "get").perform
+        end
+      end
+    end
+  end
+end

data/lib/sendio/automations/templates.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Sendio
+  module Automations
+    # Automation Templates api wrapper (ready-made automations you can create from)
+    module Templates
+      class << self
+        # List the automation template catalog. Not paginated.
+        # see more: https://developer.send.io/docs/api
+        #
+        # @param params [Hash] Optional parameters
+        # @option params [String] :category Only templates in this category: "onboarding",
+        #   "billing", "ecommerce", "engagement", "lead_capture" or "internal"
+        def list(params = {})
+          query_params = {}
+          query_params[:category] = params[:category] if params[:category]
+          Sendio::Request.new("automation-templates", query_params, "get").perform
+        end
+
+        # Retrieve one automation template in full (how_it_works, events with schemas,
+        # emails and params).
+        # see more: https://developer.send.io/docs/api
+        def get(slug)
+          Sendio::Request.new("automation-templates/#{ERB::Util.url_encode(slug.to_s)}", {}, "get").perform
+        end
+      end
+    end
+  end
+end