{"id":20040466,"url":"https://github.com/postalserver/postal-ruby","last_synced_at":"2025-06-11T22:32:15.824Z","repository":{"id":110402733,"uuid":"88879639","full_name":"postalserver/postal-ruby","owner":"postalserver","description":"A ruby client for the Postal mail platform","archived":false,"fork":false,"pushed_at":"2017-05-17T14:20:36.000Z","size":10,"stargazers_count":9,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-05T08:41:05.290Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postalserver.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2017-04-20T15:10:59.000Z","updated_at":"2024-10-25T14:02:43.000Z","dependencies_parsed_at":"2023-03-11T17:30:39.030Z","dependency_job_id":null,"html_url":"https://github.com/postalserver/postal-ruby","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/postalserver/postal-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postalserver%2Fpostal-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postalserver%2Fpostal-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postalserver%2Fpostal-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postalserver%2Fpostal-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postalserver","download_url":"https://codeload.github.com/postalserver/postal-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postalserver%2Fpostal-ruby/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259354762,"owners_count":22844924,"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","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":[],"created_at":"2024-11-13T10:42:20.187Z","updated_at":"2025-06-11T22:32:15.799Z","avatar_url":"https://github.com/postalserver.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Postal Ruby Library\n\nThis library provides an interface for sending e-mails using the [Postal](https://github.com/atech/postal) service and monitoring their status throughout their delivery journey.\n\nIt is very easy to get up and running with this library. Just follow the instructions below and you'll be sending messages before you know it.\n\n## Installation\n\nAdd the `postal-ruby` gem to your Gemfile and run `bundle install` to install it.\n\n```ruby\ngem 'postal-ruby', '~\u003e 1.0'\n```\n\n## Configuration\n\nYou'll need to tell the gem where your Postal server is using the `POSTAL_HOST` environment variable.\n\nIn order to send messages, you'll need a Server API key. You can generate one of these through your Postal web interface. This is a random string which is unique to your server and allows you authenticate to the API.  Once you've got the key, you can put it in a `POSTAL_KEY` environment variable or you can configure it as shown below:\n\n```ruby\nPostal.configure do |c|\n  c.host = \"postal.yourdomain.com\"\n  c.server_key = \"DgJyr0BxvxITaaa\"\nend\n```\n\nNo other configuration is nessessary.\n\n## Sending Messages\n\nTo send a message through the API, just follow the example below. You do not need to specify all the fields shown below.\n\n```ruby\nPostal.send_message do |m|\n  # This is the address that the message will be sent from. The address you enter here\n  # must be one of the domains configured for your mail server.\n  m.from        \"AwesomeApp \u003csales@awesome.com\u003e\"\n\n  # This is the address of the person/people receiving the message. You can pass multiple strings\n  # to this method or call `to` multiple times to add other people.\n  m.to          \"Adam Cooke \u003cadam@atechmedia.com\u003e\"\n  m.cc          \"sales@awesome.com\", \"dave@awesome.com\"\n  m.bcc         \"itsasecret@awesome.com\"\n\n  # This is the subject of the message\n  m.subject     \"Welcome to Awesome App!\"\n\n  # This is the tag. Tagging allows you to categories and produce reports based\n  # on the different types of email you send.\n  m.tag         \"welcome\"\n\n  # This is the content for the message. You must provide at least one of these options. We strongly\n  # recommend sending messages with both parts.\n  m.plain_body  \"Helo there!\"\n  m.html_body   \"\u003cp\u003eHello there!\u003c/p\u003e\"\n\n  # This adds a custom header to your outbound message. You can add as many of\n  # these as you wish.\n  m.header      \"X-Example-Header\", \"Some value goes here!\"\n\n  # This attaches a file to the message. You should provide the name of the file,\n  # the content type and the attachment content.\n  m.attach      \"terms.pdf\", \"application/pdf\", File.read(\"terms.pdf\")\nend\n```\n\nIf there are any issues with the data you've provided, you'll an `Postal::SendError` exception will be raised. This will contain a code \u0026 a message which you can use determine the issue.\n\n```ruby\nbegin\n  # Your call to `send_message`\nrescue Postal::SendError =\u003e e\n  e.code              #=\u003e UnauthenticatedFromAddress\n  e.error_message     #=\u003e The From address is not authorised to send mail from this server\nend\n```\n\nThe result of the your send call will return a `Postal::SendResult` object which you can use, if you wish, to get further information about the messages that you've just sent.\n\n```ruby\n# This will return the ID of the message that was generated for\nresult.message_id     #=\u003e e8e54169-0852-4a1f-b3b1-3a73c1ae10c7@amrp.postal.io\n\n# This will return the number of actual recipients were sent this message\nresult.recipients     #=\u003e 4\n\n# This will allow you to view the message that was sent to a given recipient. This\n# will return an Postal::Message object. See below for information about the data\n# contained within.\nmessage = result['sales@awesome.com']\nmessage.id            #=\u003e 12581\nmessage.token         #=\u003e Cssuvidz44MH\n\n# You can also access all the recipients as a hash\nresult.recipients.each do |address, message|\n  address             #=\u003e \"adam@atechmedia.com\"\n  message             #=\u003e Postal::Message object\nend\n```\n\n### Sending raw messages\n\nIf you already have a raw RFC2822 formatted message, you can send this to our API rather than the individual fields. You'll receive the same result object and exceptions as shown above.\n\n```ruby\nPostal.send_raw_message do |m|\n  # This is the address that the message will be logged as being sent from\n  m.mail_from       \"sales@awesome.com\"\n  # This is an array of addresses that will receive the message. If you wish to BCC\n  # the message to someone, they should be included here but not in the actual raw message.\n  m.rcpt_to         \"sales@awesome.com\", \"dave@awesome.com\", \"itsasecret@awesome.com\"\n  # This is the raw message as a string\n  m.data            raw_message\nend\n```\n\n## Finding messages\n\nTo find information (status, details, etc...) about a message that you've sent you can look it up by its ID. The most basic to do this is to simply call `find_by_id`.\n\n```ruby\nPostal::Message.find_by_id(12581)\n```\n\nHowever, to save your bandwidth the API will only return information that is requested by the client. By default, it will just return the `id` of the message and the `token`. When accessing methods on `Postal::Message` instances, calls will be made to our API automatically to retrieve the information needed. You can preload this data as shown below:\n\n```ruby\nmessage = Postal::Message.includes(:status, :details, :plain_body).find_by_id(12581)\nmessage.status        #=\u003e Sent\nmessage.plain_body    #=\u003e \"Hello World!\"\n# This will return but with an additional call to the API to get the html_body expansion\nmessage.html_body     =\u003e \"\u003cp\u003eHello World!\u003c/p\u003e\"\n```\n\nYou can include any of the following expansions when looking up a message. If you're going to need to use the data you can save HTTP requests by ensuring that you request them before looking it up.\n\n* `status` - includes details about the status of an outgoing message\n* `details` - includes the core details about the message such as recipient, subject etc..\n* `inspection` - includes information about spam \u0026 virus checking\n* `plain_body` - includes the plain body\n* `html_body` - includes the HTML body\n* `attachments` - includes the attachments (including the data within them)\n* `headers` - includes all the headers for the email\n* `raw_message` - includes the full RFC2822 message\n\n## Reading message information\n\nOnce you've got an `Postal::Message` object - either from the result of sending a message or by looking it up - you can use this to read properties on the message. The example below shows all the methods which are available to you on the message object.\n\n```ruby\n#\n# Core Attribtues (always available)\n#\nmessage.id                        # =\u003e The numeric ID of the message\nmessage.token                     # =\u003e The random token for this message\n\n#\n# Status Attributes (returned with the 'status' expansion)\n#\nmessage.status                    # =\u003e The status of the message\nmessage.last_delivery_attempt     # =\u003e The time of the last delivery attempt\nmessage.held?                     # =\u003e Is this message held?\nmessage.hold_expiry               # =\u003e The time the hold on this message will expire\n\n#\n# Message Details (returned with the 'details' expansion)\n#\nmessage.rcpt_to                   # =\u003e The recipient address\nmessage.mail_from                 # =\u003e The address the message was sent from\nmessage.subject                   # =\u003e The subject\nmessage.message_id                # =\u003e The message ID\nmessage.timestamp                 # =\u003e The time the message was received by us\nmessage.direction                 # =\u003e Either incoming or outgoing\nmessage.size                      # =\u003e The size of the raw message in bytes\nmessage.bounce?                   # =\u003e Is this message a bounce?\nmessage.bounce_for_id             # =\u003e The ID that this message is a bounce for\nmessage.tag                       # =\u003e The message tag\nmessage.received_with_ssl?        # =\u003e Was this message received by us with SSL\n\n#\n# Inspection Details (returned with the 'inspection' expansion)\n#\nmessage.inspected?                # =\u003e Has this message been inspected for spam/threats?\nmessage.spam?                     # =\u003e Is this message considered spam?\nmessage.spam_score                # =\u003e The spam score for the message\nmessage.threat?                   # =\u003e Is this message considered a threat?\nmessage.threat_details            # =\u003e The details of any threat\n\n#\n# Plain Body (returned with the 'plain_body' expansion)\n#\nmessage.plain_body                # =\u003e The plain body\n\n#\n# HTML Body (returned with the 'html_body' expansion)\n#\nmessage.html_body                 # =\u003e The HTML body\n\n#\n# Attachments (returned with the 'attachments' expansion)\n#\nmessage.attachments.each do |attachment|\n  attachment.filename             # =\u003e The name of an attachment\n  attachment.content_type         # =\u003e The content type of an attachment\n  attachment.size                 # =\u003e The size of an attachment in bytes\n  attachment.hash                 # =\u003e A SHA1 hash of the attachment content\n  attachment.data                 # =\u003e The raw attachment data\nend\n\n#\n# Headers (returned with the 'headers' expansion)\n#\nmessages.headers['x-something']   # =\u003e An array of all items for the x-something header\nmessages.headers.each do |key, values|\n  values.each do |value|\n    key                           # =\u003e The key for the header (in lowercase)\n    value                         # =\u003e A value for the header\n  end\nend\n\n#\n# Raw Message (returned with the 'raw_message' expansion)\n#\nmessage.raw_message               # =\u003e The full RFC2822 message\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostalserver%2Fpostal-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostalserver%2Fpostal-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostalserver%2Fpostal-ruby/lists"}