trycourier

This Gem helps you send notifications through Courier, the smartest way to design & deliver notifications. Design your notifications once using our drag & drop editor, then deliver to any channel through one API. Email, mobile push, SMS, Slack — you name it!

Installation

Add this line to your application's Gemfile:

gem 'trycourier'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install trycourier

Usage

After installing, make sure to include this line at the top of your ruby file:

require "trycourier"

To create a Courier Ruby client, all you need to do is pass in your authentication information. Then, you can start sending!

Using token authentication (most secure)

client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var

Sending a message to an individual recipient

client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
res = client.send(message: {
      "to" => {
        "email" => "foo@bar.com"
      }
      "content" => {
        "title" => "hello {{name}}",
        "body" => "Welcome to Courier!"
      },
      "data" => {
        "name" => "Ruby"
      }
  })
  puts res.request_id # if the code is 202, this will be the Courier request ID for this message

client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
res = client.send(message: {
    "event" => "your-event-id",
    "recipient" => "your-recipient-id",

    "profile" => { #optional (include any key-value pairs required by your chosen integrations. This information can also be stored in the recipient's profile in Courier)
      "email": "example@example.com",
      "phone_number": "555-867-5309"
    },

    "data" => { #any data you want to pass to a message template
      "world" => "Ruby!"
    }
  })
  puts res.message_id # if the code is 200, this will be the Courier message ID for this notification

Sending a message to an individual with metadata

client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
res = client.send(message: {
      "to" => {
        "email" => "foo@bar.com"
      }
      "content" => {
        "title" => "hello {{name}}",
        "body" => "Welcome to Courier!"
      },
      "data" => {
        "name" => "Ruby"
      },
      "metadata" => {
        "utm" => {
          "source" => "Ruby"
        },
        "tags" => ["tag-1", "tag-2"],
        "trace_id" => "feed-me-hungry"
      }
  })
  puts res.request_id # if the code is 202, this will be the Courier request ID for this message

Sending a message to an individual with granular metadata

client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
res = client.send(message: {
      "to" => {
        "email" => "foo@bar.com"
      },
      "content" => {
			  "version" => "2020-01-01",
        "elements" => [
				  {
            "type" => "text",
            "content" => "Thanks for signing up, {{name}}"
          },
          {
            "type" => "action",
            "content" => "Click Me!",
            "href" => "https://www.example.com"
          }
        ]
		  },
      "routing" => {
        "method" => "all",
        "channels" => [
          "email"
        ]
		  },
      "data" => {
        "name" => "Ruby"
      },
      "metadata" => {
        "utm" => {
          "source" => "Ruby"
        },
      },
      "channels" => {
        "email" => {
          "routing_method" => "all",
          "providers" => [
            "sendgrid",
            "mailjet"
          ],
          "metadata" => {
            "utm" => {
              "medium" => "email"
            }
          }
        }
      },
      "providers" => {
        "sendgrid" => {
          "metadata" => {
            "utm" => {
              "source" => "sendgrid"
            }
          }
        }
      }
  })
  puts res.request_id # if the code is 202, this will be the Courier request ID for this message

Advanced Usage

Lists

require "trycourier"
client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var

"""
Creating a List
"""
res = client.lists.update(list_id: list_id, request: { name: name})
puts res

"""
Example: get all lists
"""
resp = client.lists.list(
  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
)
puts resp

"""
Example: get a specific list
"""
resp = client.lists.get(list_id: "your-list-id")
puts resp

"""
Example: delete a list
"""
client.lists.delete(list_id: "your-list-id")

"""
Example: restore a list
"""
client.lists.restore(list_id: "your-list-id")

"""
Example: get a list's subscriptions
"""
resp = client.lists.get_subscribers(
    list_id: "your-list-id",
    cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
)
puts resp

"""
Example: replace many recipients to a new or existing list
"""
client.lists.update_subscribers(
    list_id: "your-list-id",
    request: [{
        recipient_id: "RECIPIENT_ID_1"
    },{
        recipient_id: "RECIPIENT_ID_2"
    }]
)

"""
Example: Example: subscribe single recipient to a new or existing list
"""
client.lists.subscribe(list_id: "your-list-id", user_id: "your-user-id")

"""
Example: unsubscribe recipient from list
"""
client.lists.unsubscribe(list_id: "your-list-id", user_id: "your-user-id")

Profiles

"""
Example: merge or create a recipient's profile
"""
resp = client.profiles.create(
  user_id: "your-user-id",
  profile: {
    "email" => "example@example.com",
    "name" => "Example Name"
  }
)

"""
Example: replace or create a recipient's profile
"""
resp = client.profiles.replace(
  user_id: "your-user-id",
  profile: {
    "email" => "example@example.com"
  }
)
puts resp['status']

"""
Example: get the subscribed lists of a recipient
"""
resp = client.profiles.get_list_subscriptions(
  user_id: "your-user-id",
  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA" #optional
)
puts resp

"""
Example: edit the contents of a recipient's profile with a patch operation
(follows JSON Patch conventions: RFC 6902).
"""
resp = client.profiles.replace(
  user_id: "your-user-id",
  profile: [
    {
      "op" => "add", #operation 1: add this email to profile
      "path" => "/parent",
      "value" => "example@example.com"
    }
    {
      "op" => "replace", #operation 2: update with new email
      "path" => "/parent",
      "value" => "jane@doe.com"
    }
    {
      "op" => "copy", #operation 3: copy that email to /emergency_contact
      "from" => "/parent",
      "path" => "/emergency_contact"
    }
    ...
  ]
)
puts resp


"""
Example: get a recipient's profile
"""
resp = client.profiles.get(user_id: "your-user-id")
puts resp

Messages

"""
Example: fetch the statuses of messages you've previously sent.
"""
resp = client.messages.list(
  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
  event: "your-event-id", # optional
  list: "your-list-id", #optional
  message_id: "your-message-id" #optional
  notification: "message-statua" #optional
  recipient: "recipient-id" # optional
)
puts resp

"""
Example: fetch the status of a message you've previously sent
"""
resp = client.messages.get(message_id: "your-message-id")
puts resp

"""
Example: fetch the array of events of a message you've previously sent.
"""
resp = client.messages.get_history(
  message_id: "your-message-id",
  type: "list-type" #optional ("FILTERED", "RENDERED", "MAPPED", "PROFILE_LOADED")
)
puts resp

Automations

"""
Example: invoke ad-hoc automation
"""
steps = [
  {
    "action" => "send"
  }
]
automation = {
  "steps" => steps
}

resp = client.automations.invoke_ad_hoc_automation(
  request: {
    automation: automation,
    brand: "your-brand-id", # optional
    data: {}, # optional
    profile: {
      "email" => "example@example.com",
    }, # optional
    recipient: "your-recipient-id", # optional
    template: "your-notification-template-id" # optional
  }
)
puts resp.run_id

"""
Example: invoke automation template
"""
resp = client.automations.invoke_automation_template(
  template_id: "your-automation-template-id",
  request: {
    brand: "your-brand-id", # optional
    data: {}, # optional
    profile: {
      "email" => "example@example.com",
    }, # optional
    recipient: "your-recipient-id", # optional
    template: "your-notification-template-id" # optional
  }
)
puts resp.run_id

Audiences

List of supported operators for audience filtering: https://www.courier.com/docs/reference/audieces/operators

"""
Example: create or update an Audience
"""
resp = client.audiences.update(
  audience_id: "your-audience-id",
  filter: {
    "operator": "EQ",
    "value": "en-US",
    "path": "locale"
  }
)

"""
Example: Get all members of an Audience
"""
resp = client.audiences.list_members(
  audience_id: "your-audience-id"
)

"""
Example: Send to an Audience
"""
client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
res = client.send(message: {
      "to" => {
        "audience_id" => "your-audience-id"
      }
      "content" => {
        "title" => "hello {{name}}",
        "body" => "Welcome to Courier!"
      },
      "data" => {
        "name" => "Ruby"
      }
  })
puts res.request_id # if the code is 202, this will be the Courier request ID for this message

Audit Events

"""
Example: List audit events
"""
resp = client.audit_events.list

"""
Example: Get a specific audit event
"""
resp = client.audit_events.get(audit_event_id: "audit-event-id")

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/trycourier/courier-ruby.

License

The gem is available as open source under the terms of the MIT License.