{"id":20438384,"url":"https://github.com/zammad/zammad-api-client-ruby","last_synced_at":"2025-07-21T08:32:55.292Z","repository":{"id":12551503,"uuid":"60560933","full_name":"zammad/zammad-api-client-ruby","owner":"zammad","description":"Zammad API Client (Ruby)","archived":false,"fork":false,"pushed_at":"2024-11-22T12:53:24.000Z","size":102,"stargazers_count":22,"open_issues_count":3,"forks_count":11,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-07-17T17:11:40.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zammad.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zammad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.AGPL.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2016-06-06T21:07:13.000Z","updated_at":"2025-03-27T15:40:15.000Z","dependencies_parsed_at":"2024-11-22T13:37:57.493Z","dependency_job_id":null,"html_url":"https://github.com/zammad/zammad-api-client-ruby","commit_stats":{"total_commits":68,"total_committers":8,"mean_commits":8.5,"dds":0.6176470588235294,"last_synced_commit":"a7cea89798643831a5a5f166b79b149bdd325a78"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zammad/zammad-api-client-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zammad%2Fzammad-api-client-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zammad%2Fzammad-api-client-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zammad%2Fzammad-api-client-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zammad%2Fzammad-api-client-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zammad","download_url":"https://codeload.github.com/zammad/zammad-api-client-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zammad%2Fzammad-api-client-ruby/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266267290,"owners_count":23902334,"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-15T09:10:45.416Z","updated_at":"2025-07-21T08:32:55.273Z","avatar_url":"https://github.com/zammad.png","language":"Ruby","readme":"# Zammad API Client (Ruby) [![Gem Version](https://badge.fury.io/rb/zammad_api.svg)](https://badge.fury.io/rb/zammad_api)\n\n## API version support\nThis client supports Zammad API version 1.0.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'zammad_api'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install zammad_api\n\n## Available objects\n\n* user\n* organization\n* group\n* ticket\n* ticket_article\n* ticket_state\n* ticket_priority\n\n## Usage\n\n### Create instance\n\n#### Username/email and password\n\n```ruby\nclient = ZammadAPI::Client.new(\n  url:      'http://localhost:3000/',\n  user:     'user',\n  password: 'some_pass'\n)\n```\n\n#### Access token\n\n```ruby\nclient = ZammadAPI::Client.new(\n  url:        'http://localhost:3000/',\n  http_token: '12345678901234567890',\n)\n```\n\n#### OAuth2\n\n```ruby\nclient = ZammadAPI::Client.new(\n  url:          'http://localhost:3000/',\n  oauth2_token: '12345678901234567890',\n)\n```\n\n## Resource management\n\nIndividual resources can be created, modified, saved, and destroyed.\n\n### Create object\n\nWith new and save:\n```ruby\ngroup = client.group.new(\n  name: 'Support',\n  note: 'Some note',\n);\ngroup.save\n\ngroup.id # id of record\ngroup.name # 'Support'\n```\n\nWith create:\n```ruby\ngroup = client.group.create(\n  name: 'Support',\n  note: 'Some note',\n);\n\ngroup.id # id of record\ngroup.name # 'Support'\n```\n\n### Fetch object\n\n```ruby\ngroup = client.group.find(123)\nputs group.inspect\n```\n### Update object\n\n```ruby\ngroup = client.group.find(123)\ngroup.name = 'Support 2'\ngroup.save\n```\n\n### Destroy object\n\n```ruby\ngroup = client.group.find(123)\ngroup.destroy\n```\n\n## Collection management\n\nA list of individual resources.\n\n### All\n\n```ruby\ngroups = client.group.all\n\ngroup1 = groups[0]\ngroup1.note = 'Some note'\ngroup1.save\n\ngroups.each {|group|\n  p \"group: #{group.name}\"\n}\n```\n\n### Search\n```ruby\ngroups = client.group.search(query: 'some name')\n\ngroup1 = groups[0]\ngroup1.note = 'Some note'\ngroup1.save\n\ngroups.each {|group|\n  p \"group: #{group.name}\"\n}\n```\n\n### All with pagination (beta)\n\n```ruby\ngroups = client.group.all\n\ngroups.page(1,3) {|group|\n  p \"group: #{group.name}\"\n\n  group.note = 'Some new note, inclued in page 1 with 3 per page'\n  group.save\n}\n\ngroups.page(2,3) {|group|\n  p \"group: #{group.name}\"\n\n  group.note = 'Some new note, inclued in page 2 with 3 per page'\n  group.save\n}\n```\n\n### Search with pagination (beta)\n```ruby\ngroups = client.group.search(query: 'some name')\n\ngroups.page(1,3) {|group|\n  p \"group: #{group.name}\"\n\n  group.note = 'Some new note, inclued in page 1 with 3 per page'\n  group.save\n}\n\ngroups.page(2,3) {|group|\n  p \"group: #{group.name}\"\n\n  group.note = 'Some new note, inclued in page 2 with 3 per page'\n  group.save\n}\n```\n\n## Perform actions on behalf of another user\n\nAs described in the [Zammad API documentation](https://docs.zammad.org/en/latest/api-intro.html#example-curl-request-on-behalf-of-a-different-user) it is possible to perfom actions on behalf other users. To use this feature you can set the attribute of the client accordingly:\n\n```ruby\nclient.on_behalf_of = 'some_login'\n```\n\nAll following actions with the client will be performed on behalf of the user with the `login` \"some_login\".\n\nTo reset this back to regular requests just set `nil`:\n\n```ruby\nclient.on_behalf_of = nil\n```\n\nIt's possible to perform only a block of actions on behalf of another user via:\n\n```ruby\nclient.perform_on_behalf_of('some_login') do\n  # ticket is created on behalf of the user with\n  # the login \"some_login\"\n  client.ticket.create(\n    ...\n  )\nend\n\n# further actions are performed regularly.\n```\n\n## Examples\n\nCreate a ticket:\n```ruby\nticket = client.ticket.create(\n  title: 'a new ticket #1',\n  state: 'new',\n  group: 'Users',\n  priority: '2 normal',\n  customer: 'some_customer@example.com',\n  article: {\n    content_type: 'text/plain', # or text/html, if not given test/plain is used\n    body: 'some body',\n    # attachments can be optional, data needs to be base64 encoded\n    attachments: [\n      'filename' =\u003e 'some_file.txt',\n      'data' =\u003e 'dGVzdCAxMjM=',\n      'mime-type' =\u003e 'text/plain',\n    ],\n  },\n)\n\nticket.id # id of record\nticket.number # uniq number of ticket\nticket.title # 'a new ticket #1'\nticket.group # 'Support'\nticket.created_at # '2022-01-01T12:42:01Z'\n# ...\n```\n\nList all new or open tickets:\n```ruby\ntickets = client.ticket.search(query: 'state:new OR state:open')\n\nticket[0].id # id of record\nticket[0].number # uniq number of ticket\nticket[0].title # 'title of ticket'\nticket[0].group # 'Support'\nticket[0].created_at # '2022-01-01T12:42:01Z'\n\ntickets.each {|ticket|\n  p \"ticket: #{ticket.number} - #{ticket.title}\"\n}\n```\n\nGet all articles of a ticket:\n```ruby\nticket = client.ticket.find(123)\narticles = ticket.articles\n\narticles[0].id # id of record\narticles[0].from # creator of article\narticles[0].to # recipients of article\narticles[0].subject # article subject\narticles[0].body # text of message\narticles[0].content_type # text/plain or text/html of .body\narticles[0].type # 'note'\narticles[0].sender # 'Customer'\narticles[0].created_at # '2022-01-01T12:42:01Z'\n\np \"ticket: #{ticket.number} - #{ticket.title}\"\narticles.each {|article|\n  p \"article: #{article.from} - #{article.subject}\"\n}\n```\n\nCreate an article for a ticket:\n```ruby\nticket = client.ticket.find(123)\n\narticle = ticket.article(\n  type: 'note',\n  subject: 'some subject 2',\n  body: 'some body 2',\n  # attachments can be optional, data needs to be base64 encoded\n  attachments: [\n    'filename' =\u003e 'some_file.txt',\n    'data' =\u003e 'dGVzdCAxMjM=',\n    'mime-type' =\u003e 'text/plain',\n  ],\n)\n\narticle.id # id of record\narticle.from # creator of article\narticle.to # recipients of article\narticle.subject # article subject\narticle.body # text of message\narticle.content_type # text/plain or text/html of .body\narticle.type # 'note'\narticle.sender # 'Customer'\narticle.created_at # '2022-01-01T12:42:01Z'\narticle.attachments.each { |attachment|\n  attachment.filename # 'some_file.txt'\n  attachment.size # 1234\n  attachment.preferences # { :\"Mime-Type\"=\u003e\"image/jpeg\" }\n  attachment.download # content of attachment / extra REST call will be executed\n}\n\np \"article: #{article.from} - #{article.subject}\"\n```\n\nCreate an article with html and inline images for a ticket:\n```ruby\nticket = client.ticket.find(123)\n\narticle = ticket.article(\n  type: 'note',\n  subject: 'some subject 2',\n  body: 'some \u003cb\u003ebody\u003c/b\u003e with an image \u003cimg src=\"data:image/jpeg;base64,/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNreQABAAQAAAAJAAD/4QMtaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLwA8P3hwYWNrZXQgYmVnaW49Iu+7vyIgaWQ9Ilc1TTBNcENlaGlIenJlU3pOVGN6a2M5ZCI/PiA8eDp4bXBtZXRhIHhtbG5zOng9ImFkb2JlOm5zOm1ldGEvIiB4OnhtcHRrPSJBZG9iZSBYTVAgQ29yZSA1LjMtYzAxMSA2Ni4xNDU2NjEsIDIwMTIvMDIvMDYtMTQ6NTY6MjcgICAgICAgICI+IDxyZGY6UkRGIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5vcmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyI+IDxyZGY6RGVzY3JpcHRpb24gcmRmOmFib3V0PSIiIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bXA6Q3JlYXRvclRvb2w9IkFkb2JlIFBob3Rvc2hvcCBDUzYgKE1hY2ludG9zaCkiIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6QzJCOTE2NzlGQUEwMTFFNjg0M0NGQjU0OUU4MTFEOEIiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6QzJCOTE2N0FGQUEwMTFFNjg0M0NGQjU0OUU4MTFEOEIiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDpDMkI5MTY3N0ZBQTAxMUU2ODQzQ0ZCNTQ5RTgxMUQ4QiIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDpDMkI5MTY3OEZBQTAxMUU2ODQzQ0ZCNTQ5RTgxMUQ4QiIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/Pv/uAA5BZG9iZQBkwAAAAAH/2wCEABQRERoTGioZGSo1KCEoNTEpKCgpMUE4ODg4OEFEREREREREREREREREREREREREREREREREREREREREREREREQBFhoaIh0iKRoaKTkpIik5RDktLTlEREREOERERERERERERERERERERERERERERERERERERERERERERERERERERP/AABEIABAADAMBIgACEQEDEQH/xABbAAEBAAAAAAAAAAAAAAAAAAAEBQEBAQAAAAAAAAAAAAAAAAAABAUQAAEEAgMAAAAAAAAAAAAAAAABAhIDESIxBAURAAICAwAAAAAAAAAAAAAAAAESABNRoQP/2gAMAwEAAhEDEQA/AJDq1rfF3Imeg/1+lFy2oR564DKWWWbweV+Buf/Z\" alt=\"Red dot\" /\u003e',\n  content_type: 'text/html', # optional, default is text/plain\n)\n\narticle.id # id of record\narticle.from # creator of article\narticle.to # recipients of article\narticle.subject # article subject\narticle.body # text of message\narticle.content_type # text/plain or text/html of .body\narticle.type # 'note'\narticle.sender # 'Customer'\narticle.created_at # '2022-01-01T12:42:01Z'\narticle.attachments.each { |attachment|\n  attachment.filename # '122.146472496@www.znuny.com'\n  attachment.size # 1167\n  attachment.preferences # { :'Mime-Type'=\u003e'image/jpeg', :'Content-ID'=\u003e'122.146472496@www.znuny.com', :'Content-Disposition'=\u003e'inline'} }\n  attachment.download # content of attachment / extra REST call will be executed\n}\n\np \"article: #{article.from} - #{article.subject}\"\n```\n\n## Testing\n\n### Setup an (empty Zammad) test env\n\n```\ngit clone git@github.com:zammad/zammad.git\ncd zammad\nexport RAILS_ENV=\"test\"\nexport APP_RESTART_CMD=\"bundle exec rake zammad:ci:app:restart\"\nscript/bootstrap.sh \u0026\u0026 echo '' \u003e log/test.log\ncp contrib/auto_wizard_test.json auto_wizard.json\nbundle exec rake zammad:ci:test:start\n```\n\n### Execute client tests\n\nRun tests via `rake spec`. (Remember to export the vars above if you are running this in another shell.)\n\n## Publishing\n\n1. Update version in [version.rb](lib/zammad_api/version.rb).\n2. Add release to [CHANGELOG.md](CHANGELOG.md)\n3. Commit.\n4. Test build.\n```\n\u003e rake build\nzammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem.\n```\n5. Release\n```\n\u003e rake release\nzammad_api 1.0.7 built to pkg/zammad_api-1.0.7.gem.\nTag v1.0.7 has already been created.\nPushing gem to https://rubygems.org...\nYou have enabled multi-factor authentication. Please enter OTP code.\nCode:   ......\nSuccessfully registered gem: zammad_api (1.0.7)\nPushed zammad_api 1.0.7 to https://rubygems.org\n\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on [GitHub](https://github.com/zammad/zammad-api-client-ruby). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzammad%2Fzammad-api-client-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzammad%2Fzammad-api-client-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzammad%2Fzammad-api-client-ruby/lists"}