Ruby SDK

Send email with Ruby

Install the official Parcel Wing Ruby SDK, configure a server-side API key, and send your first transactional email.

Requirements

Ruby 3.0 or newer.
Bundler or RubyGems available in your project.
A Parcel Wing API key stored as PARCELWING_API_KEY.
A verified sending domain for your from address.

Install the SDK

The official Ruby SDK is published as parcelwing.

Terminal

gem install parcelwing

Send your first email

Create a ParcelWing::Client and call parcelwing.emails.send.

send.rb

require "parcelwing"
 
parcelwing = ParcelWing::Client.new(
  api_key: ENV.fetch("PARCELWING_API_KEY")
)
 
emails = parcelwing.emails.send(
  from: "Acme <[email protected]>",
  to: "[email protected]",
  subject: "Hello from Parcel Wing",
  html: "<strong>It works!</strong>",
  text: "It works."
)
 
puts emails.first.fetch("id")

Configuration

Set a custom base URL, timeout, or headers when testing locally or tagging traffic from your app.

parcelwing_client.rb

parcelwing = ParcelWing::Client.new(
  api_key: ENV.fetch("PARCELWING_API_KEY"),
  base_url: ENV.fetch("PARCELWING_BASE_URL", "https://parcelwing.com"),
  timeout: 30,
  headers: {
    "X-App-Name" => "acme-ruby-app"
  }
)

Send to multiple recipients

Use arrays, reply-to addresses, and tags when you need richer message metadata.

bulk.rb

parcelwing.emails.send(
  from: "Acme <[email protected]>",
  to: ["[email protected]", "[email protected]"],
  reply_to: "[email protected]",
  subject: "Hello from Parcel Wing",
  text: "Plain text body",
  html: "<p>HTML body</p>",
  tags: { campaign: "welcome" }
)

Use a template

Use template_alias and template_params for reusable product and lifecycle messages.

templates.rb

emails = parcelwing.emails.send(
  from: "Acme <[email protected]>",
  to: "[email protected]",
  template_alias: "welcome",
  template_params: {
    first_name: "Ada",
    workspace_name: "Acme"
  }
)

Handle errors

API and transport failures raise ParcelWing::Error with status, type, code, and request ID fields.

errors.rb

begin
  parcelwing.emails.send(
    from: "Acme <[email protected]>",
    to: "[email protected]",
    subject: "Hello",
    text: "Hello!"
  )
rescue ParcelWing::Error => error
  warn "Parcel Wing error: #{error.message}"
  warn "status=#{error.status} type=#{error.type} code=#{error.code}"
  warn "request_id=#{error.request_id}"
end

Framework guides

Ruby on Rails

Use Parcel Wing from a Ruby on Rails application with server-side API key handling.

Sinatra

Use Parcel Wing from a Sinatra application with server-side API key handling.

Rack

Use Parcel Wing from a Rack application with server-side API key handling.

Padrino

Use Parcel Wing from a Padrino application with server-side API key handling.

Cuba

Use Parcel Wing from a Cuba application with server-side API key handling.

Hanami

Use Parcel Wing from a Hanami application with server-side API key handling.

Roda

Use Parcel Wing from a Roda application with server-side API key handling.

Grape

Use Parcel Wing from a Grape application with server-side API key handling.