update readme

Author: yanchuk

README.md

@@ -2,16 +2,45 @@
 [![docs](https://shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/mailtrap)
 [![gem](https://shields.io/gem/v/mailtrap)](https://rubygems.org/gems/mailtrap)
 [![downloads](https://shields.io/gem/dt/mailtrap)](https://rubygems.org/gems/mailtrap)
+[![license](https://shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
 
+# Mailtrap Ruby client - Official
 
+## Prerequisites
 
-# Official Mailtrap Ruby client
+To get the most out of this official Mailtrap.io Ruby SDK:
 
-This Ruby gem offers integration with the [official API](https://api-docs.mailtrap.io/) for [Mailtrap](https://mailtrap.io).
+* [Create a Mailtrap account](https://mailtrap.io/signup)
+* [Verify your domain](https://mailtrap.io/sending/domains)
+
+## Supported functionality
 
-Quickly add email sending functionality to your Ruby application with Mailtrap.
+This Ruby gem offers integration with the [official API](https://api-docs.mailtrap.io/) for [Mailtrap](https://mailtrap.io).
 
-(This client uses API v2, for v1 refer to [this documentation](https://mailtrap.docs.apiary.io/))
+Quickly integrate Mailtrap with your Ruby application.
+
+Currently, with this SDK you can:
+
+* **Email API/SMTP**
+  * Send an email (Transactional and Bulk streams)
+  * Send an email with a template
+  * Send a batch of emails (Transactional and Bulk streams)
+* **Email Sandbox (Testing)**
+  * Send an email
+  * Send an email with a template
+  * Message management
+  * Inbox management
+  * Project management
+* **Contact management**
+  * Contacts CRUD
+  * Lists CRUD
+  * Contact fields CRUD
+* **General**
+  * Templates CRUD
+  * Suppressions management (find and delete)
+  * Account access management
+  * Permissions management
+  * List accounts you have access to
 
 ## Installation
 
@@ -23,21 +52,51 @@ gem 'mailtrap'
 
 And then execute:
 
-    $ bundle install
+```bash
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install mailtrap
+```bash
+gem install mailtrap
+```
 
 ## Usage
 
+### Minimal
+
+```ruby
+require 'mailtrap'
+
+# For this example to work, you need to set up a sending domain,
+# and obtain a token that is authorized to send from the domain.
+
+TOKEN = "<YOUR-TOKEN-HERE>"
+SENDER_EMAIL = "<[email protected]>"
+RECIPIENT_EMAIL = "<[email protected]>"
+
+client = Mailtrap::Client.new(api_key: TOKEN)
+sender = { name: "Mailtrap Test", email: SENDER_EMAIL }
+
+client.send(
+  from: sender,
+  to: [{ email: RECIPIENT_EMAIL }],
+  subject: "Hello from Mailtrap!",
+  text: "Welcome to Mailtrap Sending!"
+)
+```
+
 ### Ruby on Rails
 
 ```ruby
-# place this code in config/environments/production.rb:
+# config/environments/production.rb
 config.action_mailer.delivery_method = :mailtrap
+config.action_mailer.mailtrap_settings = {
+  api_key: 'your-api-key'
+}
 
-# then set the MAILTRAP_API_KEY environment variable
+# Set the MAILTRAP_API_KEY environment variable
 # using your hosting solution.
 ```
 
@@ -70,7 +129,49 @@ client.send(
   subject: 'You are awesome!',
   text: 'Congrats for sending test email with Mailtrap!'
 )
+```
+
+### Send Email Using Template
+
+```ruby
+require 'mailtrap'
+
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+
+mail = Mailtrap::Mail.from_template(
+  from: { email: '[email protected]', name: 'Mailtrap Test' },
+  to: [
+    { email: '[email protected]' }
+  ],
+  template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+  template_variables: {
+    'user_name' => 'John Doe'
+  }
+)
+
+client.send(mail)
+```
+
+### Email Sandbox (Testing)
+
+```ruby
+require 'mailtrap'
+
+# Send to sandbox inbox for testing
+client = Mailtrap::Client.new(
+  api_key: 'your-api-key',
+  sandbox: true,
+  inbox_id: 12
+)
 
+client.send(
+  from: { email: '[email protected]', name: 'Mailtrap Test' },
+  to: [
+    { email: '[email protected]' }
+  ],
+  subject: 'Test Email',
+  text: 'This is a test email sent to sandbox inbox'
+)
 ```
 
 ### Batch Sending
@@ -111,7 +212,7 @@ client.send_batch(
 require 'mailtrap'
 
 client = Mailtrap::Client.new(api_key: 'your-api-key')
-templates = Mailtrap::EmailTemplatesAPI.new 3229, client
+templates = Mailtrap::EmailTemplatesAPI.new(3229, client)
 
 templates.create(
   name: 'Welcome Email',
@@ -122,37 +223,60 @@ templates.create(
 )
 ```
 
-Refer to the [`examples`](examples) folder for more examples:
+### Contacts API
 
-- [Full](examples/full.rb)
-- [Email template](examples/email_template.rb)
-- [Batch Sending](examples/batch.rb)
-- [ActionMailer](examples/action_mailer.rb)
-- [Email Templates API](examples/email_templates_api.rb)
+```ruby
+require 'mailtrap'
 
-### Content-Transfer-Encoding
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+contacts = Mailtrap::ContactsAPI.new(3229, client)
+contact_lists = Mailtrap::ContactListsAPI.new(3229, client)
+contact_fields = Mailtrap::ContactFieldsAPI.new(3229, client)
+
+# Create contact list
+list = contact_lists.create(name: 'Test List')
+
+# Create contact field
+field = contact_fields.create(
+  name: 'Nickname',
+  data_type: 'text',
+  merge_tag: 'nickname'
+)
 
-`mailtrap` gem uses Mailtrap API to send emails. Mailtrap API does not try to
-replicate SMTP. That is why you should expect some limitations when it comes to
-sending. For example, `/api/send` endpoint ignores `Content-Transfer-Encoding`
-(see `headers` in the [API documentation](https://railsware.stoplight.io/docs/mailtrap-api-docs/67f1d70aeb62c-send-email)).
-Meaning your recipients will receive emails only in the default encoding which
-is `quoted-printable`, if you send with Mailtrap API.
+# Create contact
+contact = contacts.create(
+  email: 'test@example.com',
+  fields: { field.merge_tag => 'John Doe' },
+  list_ids: [list.id]
+)
 
-For those who need to use `7bit` or any other encoding, SMTP provides
-better flexibility in that regard. Go to your _Mailtrap account_ → _Email Sending_
-→ _Sending Domains_ → _Your domain_ → _SMTP/API Settings_ to find the SMTP
-configuration example.
+# Get contact
+contact = contacts.get(contact.id)
+
+# Update contact
+contacts.upsert(
+  contact.id,
+  email: '[email protected]',
+  fields: { field.merge_tag => 'Jane Doe' }
+)
+
+# List contacts
+contacts.list
+
+# Delete contact
+contacts.delete(contact.id)
+```
 
 ### Multiple Mailtrap Clients
 
-You can configure two Mailtrap clients to operate simultaneously. This setup is
+You can configure multiple Mailtrap clients to operate simultaneously. This setup is
 particularly useful when you need to send emails using both the transactional
-and bulk APIs. Refer to the configuration example below:
+and bulk APIs, or when using sandbox for testing:
 
 ```ruby
 # config/application.rb
 ActionMailer::Base.add_delivery_method :mailtrap_bulk, Mailtrap::ActionMailer::DeliveryMethod
+ActionMailer::Base.add_delivery_method :mailtrap_sandbox, Mailtrap::ActionMailer::DeliveryMethod
 
 # config/environments/production.rb
 config.action_mailer.delivery_method = :mailtrap
@@ -163,11 +287,57 @@ config.action_mailer.mailtrap_bulk_settings = {
   api_key: 'your-api-key',
   bulk: true
 }
+config.action_mailer.mailtrap_sandbox_settings = {
+  api_key: 'your-api-key',
+  sandbox: true,
+  inbox_id: 12
+}
 
 # app/mailers/foo_mailer.rb
-mail(delivery_method: :mailtrap_bulk)
+mail(delivery_method: :mailtrap_bulk)  # For bulk sending
+mail(delivery_method: :mailtrap_sandbox)  # For sandbox testing
 ```
 
+## Examples
+
+Refer to the [`examples`](examples) folder for the source code of this and other advanced examples:
+
+### Contacts API
+
+* [Contacts](examples/contacts_api.rb)
+
+### Sending API
+
+* [Full](examples/full.rb)
+* [Email template](examples/email_template.rb)
+* [ActionMailer](examples/action_mailer.rb)
+
+### Batch Sending API
+
+* [Batch Sending](examples/batch.rb)
+
+### Templates API
+
+* [Email Templates API](examples/email_templates_api.rb)
+
+### Email Sandbox (Testing) API
+
+* [Sandbox examples in Full](examples/full.rb)
+
+## Content-Transfer-Encoding
+
+`mailtrap` gem uses Mailtrap API to send emails. Mailtrap API does not try to
+replicate SMTP. That is why you should expect some limitations when it comes to
+sending. For example, `/api/send` endpoint ignores `Content-Transfer-Encoding`
+(see `headers` in the [API documentation](https://railsware.stoplight.io/docs/mailtrap-api-docs/67f1d70aeb62c-send-email)).
+Meaning your recipients will receive emails only in the default encoding which
+is `quoted-printable`, if you send with Mailtrap API.
+
+For those who need to use `7bit` or any other encoding, SMTP provides
+better flexibility in that regard. Go to your _Mailtrap account_ → _Email Sending_
+→ _Sending Domains_ → _Your domain_ → _SMTP/API Settings_ to find the SMTP
+configuration example.
+
 ## Migration guide v1 → v2
 
 Change `Mailtrap::Sending::Client` to `Mailtrap::Client`.