Parcel Wing Ruby SDK

Official Ruby SDK for the Parcel Wing API.

gem install parcelwing

Or add it to your Gemfile:

gem "parcelwing"

Requirements

• Ruby 3.0+
• A Parcel Wing API key
• A verified sending domain in Parcel Wing

Send an email

require "parcelwing"

parcelwing = ParcelWing::Client.new(api_key: "pw_live_your_api_key_here")

emails = parcelwing.emails.send(
  from: "Parcel Wing <hello@yourdomain.com>",
  to: "you@example.com",
  subject: "Hello from Parcel Wing",
  html: "<strong>It works!</strong>",
  text: "It works!"
)

puts emails

emails.send returns an array of queued email objects:

[
  {
    "object" => "email",
    "id" => "...",
    "to" => "you@example.com",
    "status" => "queued"
  }
]

Configuration

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-My-App" => "my-ruby-app"
  }
)

Emails

parcelwing.emails.send(
  from: "Parcel Wing <hello@yourdomain.com>",
  to: ["alice@example.com", "bob@example.com"],
  subject: "Hello from Parcel Wing",
  text: "Plain text body",
  html: "<p>HTML body</p>",
  reply_to: "support@yourdomain.com",
  tags: {
    campaign: "welcome"
  }
)

You can also send using a stored template:

parcelwing.emails.send(
  from: "Parcel Wing <hello@yourdomain.com>",
  to: "you@example.com",
  template_alias: "welcome",
  template_params: {
    first_name: "Ada"
  }
)

Contacts

contact = parcelwing.contacts.create(
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace",
  attributes: {
    plan: "flight"
  }
)

contacts = parcelwing.contacts.list(limit: 25, status: "active")
contact = parcelwing.contacts.get(contact.fetch("id"))
updated = parcelwing.contacts.update(contact.fetch("id"), first_name: "Augusta")
parcelwing.contacts.delete(contact.fetch("id"))

Batch create contacts by passing an array:

result = parcelwing.contacts.create([
  { email: "alice@example.com" },
  { email: "bob@example.com" }
])

Segments

segment = parcelwing.segments.create(
  name: "Active customers",
  filter_criteria: {
    version: 1,
    match: "all",
    conditions: [
      {
        field: "status",
        operator: "equals",
        value: "active"
      }
    ]
  }
)

segments = parcelwing.segments.list(include_counts: true)
segment = parcelwing.segments.get(segment.fetch("id"))
parcelwing.segments.update(segment.fetch("id"), name: "Active subscribers")
parcelwing.segments.delete(segment.fetch("id"))

Topics

topic = parcelwing.topics.create(
  name: "Product updates",
  description: "News and feature announcements",
  default_subscription: "opt_in",
  visibility: "public"
)

topics = parcelwing.topics.list(active: true)
topic = parcelwing.topics.get(topic.fetch("id"))
parcelwing.topics.update(topic.fetch("id"), description: "Product news")
parcelwing.topics.delete(topic.fetch("id"))

Automations

event = parcelwing.automations.track(
  event_name: "signup_completed",
  contact_id: "contact-id",
  payload: {
    plan: "launch"
  },
  event_id: "signup-123"
)

Error handling

API and transport errors raise ParcelWing::Error.

begin
  parcelwing.emails.send(
    from: "Parcel Wing <hello@yourdomain.com>",
    to: "you@example.com",
    subject: "Hello",
    text: "Hello!"
  )
rescue ParcelWing::Error => e
  warn "Parcel Wing error: #{e.message}"
  warn "status=#{e.status} type=#{e.type} code=#{e.code} request_id=#{e.request_id}"
end

Development

bundle install
bundle exec rake test

Build the gem locally:

gem build parcelwing.gemspec

Install the local build:

gem install ./parcelwing-0.1.0.gem