Ruby SDK

Send email with Ruby on Rails

Use the Parcel Wing Ruby SDK from Rails services, controllers, and background jobs.

Install the SDK

The official Ruby SDK is published as parcelwing.

Terminal

gem install parcelwing

Configure Rails

Load your API key and default sender from encrypted credentials or deployment-only environment variables.

config/initializers/parcelwing.rb

# config/initializers/parcelwing.rb
Rails.application.config.x.parcelwing = ActiveSupport::OrderedOptions.new
Rails.application.config.x.parcelwing.api_key = ENV.fetch("PARCELWING_API_KEY")
Rails.application.config.x.parcelwing.from_email = ENV.fetch("PARCELWING_FROM_EMAIL")

Create a mail service

Wrap common lifecycle messages in a service class so controllers, jobs, and models share one sending interface.

app/services/parcelwing_mailer.rb

# app/services/parcelwing_mailer.rb
require "parcelwing"
 
class ParcelwingMailer
  def initialize(client: default_client)
    @client = client
  end
 
  def send_welcome(email:, first_name: nil)
    emails = @client.emails.send(
      from: Rails.configuration.x.parcelwing.from_email,
      to: email,
      template_alias: "welcome",
      template_params: { first_name: first_name.presence || "friend" }
    )
 
    emails.first
  end
 
  private
 
  def default_client
    ParcelWing::Client.new(api_key: Rails.configuration.x.parcelwing.api_key)
  end
end

Send from a controller

Validate inputs before calling the service, then return the queued Parcel Wing message ID.

app/controllers/welcome_emails_controller.rb

# app/controllers/welcome_emails_controller.rb
class WelcomeEmailsController < ApplicationController
  def create
    message = ParcelwingMailer.new.send_welcome(
      email: params.require(:email),
      first_name: params[:first_name]
    )
 
    render json: { id: message.fetch("id") }
  rescue ParcelWing::Error => error
    Rails.logger.warn("Parcel Wing request_id=#{error.request_id} code=#{error.code}")
    render json: { error: error.code, request_id: error.request_id }, status: error.status
  end
end

Production notes

Keep PARCELWING_API_KEY in server-side environment variables.
Use saved templates for onboarding, invites, receipts, and account notifications.
Log request_id from ParcelWing::Error for support and debugging.