{"id":18728747,"url":"https://github.com/rubyonworld/postageapp-ruby","last_synced_at":"2025-10-14T10:08:41.980Z","repository":{"id":174008036,"uuid":"542159160","full_name":"RubyOnWorld/postageapp-ruby","owner":"RubyOnWorld","description":"This gem is used to integrate Ruby apps with PostageApp service. Personalized high-volume email sending can be offloaded to PostageApp via a simple JSON-based API.","archived":false,"fork":false,"pushed_at":"2022-09-27T23:41:50.000Z","size":315,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-12T23:09:33.794Z","etag":null,"topics":["app","postage","postageapp","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RubyOnWorld.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-27T15:31:36.000Z","updated_at":"2022-09-28T01:26:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"1112f6e7-42f8-4980-bec7-f8c1964390f1","html_url":"https://github.com/RubyOnWorld/postageapp-ruby","commit_stats":null,"previous_names":["rubyonworld/postageapp-ruby"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RubyOnWorld/postageapp-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fpostageapp-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fpostageapp-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fpostageapp-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fpostageapp-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RubyOnWorld","download_url":"https://codeload.github.com/RubyOnWorld/postageapp-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RubyOnWorld%2Fpostageapp-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018768,"owners_count":26086449,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app","postage","postageapp","ruby"],"created_at":"2024-11-07T14:24:12.934Z","updated_at":"2025-10-14T10:08:41.955Z","avatar_url":"https://github.com/RubyOnWorld.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [PostageApp](https://postageapp.com/) Ruby Gem [![Build Status](https://secure.travis-ci.org/postageapp/postageapp-ruby.png)](http://travis-ci.org/postageapp/postageapp-ruby)\n\nThis gem is used to integrate Ruby apps with [PostageApp](https://postageapp.com/)\nservice. Personalized high-volume email sending can be offloaded to PostageApp\nvia a simple [JSON-based API](https://dev.postageapp.com/api).\n\n### [API Documentation](https://dev.postageapp.com/api/)\n\n# Installation\n\n## Rails 5.2 and newer\n\nAdd the `postageapp` gem to your Gemfile:\n\n    gem 'postageapp'\n\nThen from the Rails project's root run:\n\n    bundle install\n\nFor authentication, add your project's PostageApp credentials to the\nRails Encrypted Credentials:\n\n    rails credentials:edit\n\nThe format of this entry should be:\n\n    postageapp:\n      api_key: __PROJECT_API_KEY__\n\nWhere that will be picked up by the plugin when Rails starts.\n\n## Rails 4.x and newer\n\nAdd the `postageapp` gem to your Gemfile:\n\n    gem 'postageapp'\n\nThen from the Rails project's root run:\n\n    bundle install\n    bin/rails generate postageapp --api-key PROJECT_API_KEY\n\n## Legacy Versions of Rails\n\n* [Rails 3.x](doc/RAILS3.md)\n* [Rails 2.3.x](doc/RAILS2.md)\n\n## Sinatra / Rack / Others\n\nAdd the `postageapp` gem to your Gemfile:\n\n    gem 'postageapp'\n\nThen from the project's root run:\n\n    bundle install\n\nThe configuration will need to be loaded before executing any API calls:\n\n```ruby\nrequire 'postageapp'\n\nPostageApp.configure do |config|\n  config.api_key = 'PROJECT_API_KEY'\nend\n```\n\nIf it's more convenient, setting the `POSTAGEAPP_API_KEY` environment variable\nwith the appropriate API key will also work.\n\n# Usage\n\nHere's an example of sending a message using the\n[`send_message`](https://dev.postageapp.com/api/send_message) API call:\n\n```ruby\nrequest = PostageApp::Request.new(\n  :send_message,\n  {\n    headers: {\n      from: 'sender@example.com',\n      subject: 'Email Subject'\n    },\n    recipients: 'recipient@example.com',\n    content: {\n      'text/plain' =\u003e 'text email content',\n      'text/html' =\u003e 'html email content'\n    },\n    attachments: {\n      'document.pdf' =\u003e {\n        content_type: 'application/pdf',\n        content: Base64.encode64(File.open('/path/to/document.pdf', 'rb').read)\n      }\n    }\n  }\n)\n\nresponse = request.send\n```\n\n`PostageApp::Response` object allows you to check the status:\n\n    \u003e\u003e response.status\n    =\u003e 'ok'\n\nAlternatively you may use:\n\n    \u003e\u003e response.fail?\n    =\u003e false\n    \u003e\u003e response.ok?\n    =\u003e true\n\nResponse usually comes back with data:\n\n    \u003e\u003e response.data\n    =\u003e { 'message' =\u003e { 'id' =\u003e '12345' }}\n\n# Recipient Override\n\nSometimes you don't want to send emails to real people in your application. For\nthat there's an ability to override to what address all emails will be\ndelivered. All you need to do is modify configuration block like this (in Rails\nprojects it's usually found in `RAILS_ROOT/config/initializers/postageapp.rb`):\n\n```ruby\nPostageApp.configure do |config|\n  config.api_key = 'PROJECT_API_KEY'\n\n  unless (Rails.env.production?)\n    config.recipient_override = 'you@example.com'\n  end\nend\n```\n\n# ActionMailer Integration\n\nYou can quickly convert your existing mailers to use PostageApp service by\nsimply changing `class MyMailer \u003c ActionMailer::Base` to\n`class MyMailer \u003c PostageApp::Mailer`. When using ActionMailer from outside\nof Rails, this will have to be loaded manually:\n\n```ruby\nrequire 'postageapp/mailer'\n```\n\nThere are custom methods that allow setting of `template` and `variables` parts\nof the API call. They are `postageapp_template` and `postageapp_variables`.\nExamples how they are used are below. For details what they do please see\n[documentation](https://dev.postageapp.com/api/)\n\nPlease note that `deliver` method will return `PostageApp::Response` object.\nThis way you can immediately check the status of the delivery. For example:\n\n    response = UserMailer.welcome_email(@user).deliver\n    response.ok?\n    # =\u003e true\n\n## Mailer Base Class\n\nHere's an example of a mailer using the `PostageApp::Mailer` base class:\n\n```ruby\nrequire 'postageapp/mailer'\n\nclass Notifier \u003c PostageApp::Mailer\n  def signup_notification\n    attachments['example.zip'] = File.read('/path/to/example.zip')\n\n    headers['Special-Header'] = 'SpecialValue'\n\n    # PostageApp specific elements:\n    postageapp_template 'example_template'\n    postageapp_variables 'global_variable' =\u003e 'value'\n\n    # You may set api key for a specific mailers\n    postageapp_api_key '123456abcde'\n\n    # You can manually specify uid for the message payload.\n    # Make sure it's sufficiently unique.\n    postageapp_uid Digest::SHA1.hexdigest([ @user.id, Time.now ].to_s)\n\n    mail(\n      from: 'test@test.test',\n      subject: 'Test Message',\n      to: {\n        'recipient_1@example.com' =\u003e { 'variable' =\u003e 'value' },\n        'recipient_2@example.com' =\u003e { 'variable' =\u003e 'value' }\n      }\n    )\n  end\nend\n```\n\nAPI of previous ActionMailer is partially supported under Rails 3 environment.\nPlease note that it's not 100% integrated, some methods/syntax will not work.\nYou may still define you mailers in this way (but really shouldn't):\n\n```ruby\nrequire 'postageapp/mailer'\n\nclass Notifier \u003c PostageApp::Mailer\n  def signup_notification\n    from 'sender@example.com'\n    subject 'Test Email'\n\n    mail(to: 'recipient@example.com')\n  end\nend\n```\n\n#### Interceptors\n\nHere's an example of using an interceptor:\n\n```ruby\nclass DevelopmentPostageappInterceptor\n  def self.delivering_email(postageapp_msg)\n    postageapp_msg.arguments[\"headers\"][:subject] =\n      \"[#{postageapp_msg.arguments[\"recipients\"]}] #{postageapp_msg.arguments[\"headers\"][:subject]}\"\n\n    postageapp_msg.arguments[\"recipients\"] = \"test@example.com\"\n\n    # Deliveries can be disabled if required\n    # postageapp_msg.perform_deliveries = false\n  end\nend\n```\n\n# Automatic resending in case of failure\n\nFor those rare occasions when the API is not reachable or unresponsive,\nthis gem will temporarily store requests and then will attempt to resend them\nwith the next successful connection. In Rails environment it will create a\nfolder: `RAILS_ROOT/tmp/postageapp_failed_requests` and save all failed\nrequests there. On successful resend file for that request will be deleted.\n\nFor projects other than Rails you'll need to tell where the `project_root` is:\n\n```ruby\nPostageApp.configure do |config|\n  config.api_key = 'PROJECT_API_KEY'\n  config.project_root = \"/path/to/your/project\"\nend\n```\n\n# Configuration Details\n\nConfiguration can be done either via Ruby code directly, by environment\nvariables, or by a combination of both. Where both are supplied, the\nRuby setting will take precedence.\n\n## Configuration Arguments\n\nThese can all be set with `PostageApp.config`:\n\n* `api_key`: Project API key to use (required for project API functions)\n* `account_api_key`: Account API key to use (required for account API functions)\n* `postback_secret`: Secret to use for validating ActionMailbox requests (optional)\n* `project_root`: Project root for logging purposes (default: current working directory)\n* `recipient_override`: Override sender on `send_message` calls (optional)\n* `logger`: Logger instance to use (optional)\n* `secure`: Enable verifying TLS connections (default: `true`)\n* `verify_tls`: Enable TLS certificate verification (default: `true`)\n* `verify_certificate`: Alias for `verify_tls`\n* `host`: API host to contact (default: `api.postageapp.com`)\n* `port`: API port to contact (default: `443`)\n* `scheme`: HTTP scheme to use (default: `https`)\n* `protocol`: Alias for `scheme`\n* `proxy_username`: SOCKS5 proxy username (optional)\n* `proxy_user`: Alias for `proxy_username`\n* `proxy_password`: SOCKS5 proxy password (optional)\n* `proxy_pass`: Alias for `proxy_password`\n* `proxy_host`: SOCKS5 proxy host (optional)\n* `proxy_port`: SOCKS5 proxy port (default: `1080`)\n* `open_timeout`: Timeout in seconds when initiating requests (default: `5`)\n* `http_open_timeout`: Alias for `open_timeout`\n* `read_timeout`: Timeout in seconds when awaiting responses (default: `10`)\n* `http_read_timeout`: Alias for `read_timeout`\n* `retry_methods`: Which API calls to retry, comma and/or space separated (default: `send_message`)\n* `requests_to_resend`: Alias for `retry_methods`\n* `framework`: Framework used (default: `Ruby`)\n* `environment`: Environment to use (default: `production`)\n\nA typical configuration involves setting the project API key:\n\n    PostageApp.config do |config|\n      config.api_key = 'PROJECT_API_KEY'\n    end\n\nWhere additional settings can be applied as necessary.\n\n## Environment Variables\n\nMost configuration parameters can be set via the environment:\n\n* `POSTAGEAPP_API_KEY`: Project API key to use (required for project API functions)\n* `POSTAGEAPP_ACCOUNT_API_KEY`: Account API key to use (required for account API functions)\n* `POSTAGEAPP_POSTBACK_SECRET`: Secret to use for validating ActionMailbox requests (optional)\n* `POSTAGEAPP_PROJECT_ROOT`: Project root for logging purposes (default: current working directory)\n* `POSTAGEAPP_RECIPIENT_OVERRIDE`: Override sender on `send_message` calls (optional)\n* `POSTAGEAPP_VERIFY_TLS`:  (default: `true`)\n* `POSTAGEAPP_VERIFY_CERTIFICATE`: Alias for `POSTAGEAPP_VERIFY_TLS`\n* `POSTAGEAPP_HOST`: API host to contact (default: `api.postageapp.com`)\n* `POSTAGEAPP_PORT`: API port to contact (default: `443`)\n* `POSTAGEAPP_SCHEME`: HTTP scheme to use (default: `https`)\n* `POSTAGEAPP_PROTOCOL`: Alias for `POSTAGEAPP_SCHEME`\n* `POSTAGEAPP_PROXY_USERNAME`: SOCKS5 proxy username (optional)\n* `POSTAGEAPP_PROXY_USER`: Alias for `POSTAGEAPP_PROXY_USERNAME`\n* `POSTAGEAPP_PROXY_PASSWORD`: SOCKS5 proxy password (optional)\n* `POSTAGEAPP_PROXY_PASS`: Alias for `POSTAGEAPP_PROXY_PASSWORD`\n* `POSTAGEAPP_PROXY_HOST`: SOCKS5 proxy host (optional)\n* `POSTAGEAPP_PROXY_PORT`: SOCKS5 proxy port (default: `1080`)\n* `POSTAGEAPP_OPEN_TIMEOUT`: Timeout in seconds when initiating requests (default: `5`)\n* `POSTAGEAPP_HTTP_OPEN_TIMEOUT`: Alias for `POSTAGEAPP_OPEN_TIMEOUT`\n* `POSTAGEAPP_READ_TIMEOUT`: Timeout in seconds when awaiting responses (default: `10`)\n* `POSTAGEAPP_HTTP_READ_TIMEOUT`: Alias for `POSTAGEAPP_READ_TIMEOUT`\n* `POSTAGEAPP_RETRY_METHODS`: Which API calls to retry, comma and/or space separated (default: `send_message`)\n* `POSTAGEAPP_REQUESTS_TO_RESEND`: Alias for `POSTAGEAPP_RETRY_METHODS`\n* `POSTAGEAPP_FRAMEWORK`: Framework used (default: `Ruby`)\n* `POSTAGEAPP_ENVIRONMENT`: Environment to use (default: `production`)\n\n# Copyright and Licensing\n\n(C) 2011-2019 Scott Tadman, Oleg Khabarov, [PostageApp](https://postageapp.com/)\n\nThis is released under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyonworld%2Fpostageapp-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyonworld%2Fpostageapp-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyonworld%2Fpostageapp-ruby/lists"}