mailgun-ruby 1.4.5 → 1.4.6

data/docs/ApiKeys.md

@@ -1,65 +0,0 @@
-Mailgun - API Keys
-====================
-
-This is the Mailgun Ruby *API Keys* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions.
-
-Usage - API Keys
------------------------
-
-```ruby
-# First, instantiate the Mailgun Client with your API key
-mg_client = Mailgun::Client.new('your-api-key', 'api.mailgun.net', 'v1')
-api_keys = Mailgun::ApiKeys.new(mg_client)
-```
-
-API Keys methods:
-
-```ruby
-# List API keys
-api_keys.list
-
-# List API keys filtered by kind and domain
-api_keys.list(kind: 'domain', domain_name: 'my.perfect.domain')
-
-# Create a user API key
-api_keys.create(
-  kind: 'user',
-  role: 'admin',
-  description: 'desc'
-)
-
-# Create a sending key for a domain, expiring in 1 day
-api_keys.create(
-  kind: 'domain',
-  domain_name: 'my.perfect.domain',
-  role: 'sending',
-  expiration: 86_400
-)
-
-# Delete an API key
-api_keys.remove('key-id')
-
-# Regenerate the public API key
-api_keys.regenerate
-```
-
-Supported `create` options:
-
-| Option        | Description |
-|---------------|-------------|
-| `kind`        | Type of API key: `domain`, `user` or `web`. Defaults to `user` |
-| `role`        | Key role: `admin`, `basic`, `sending` (for `domain` keys) or `developer` |
-| `domain_name` | Domain to associate with the key, for `domain` keys |
-| `description` | Key description |
-| `expiration`  | Key lifetime in seconds, must be greater than 0 if set |
-| `user_id`     | API key user's ID, should be provided for `web` keys |
-| `user_name`   | API key user's name |
-| `email`       | API key user's email address, should be provided for `web` keys |
-
-More Documentation
-------------------
-See the official [Mailgun API Keys Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/keys)
-for more information

data/docs/DomainKeys.md

@@ -1,49 +0,0 @@
-Mailgun - DomainKeys
-====================
-
-This is the Mailgun Ruby *DomainKeys* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions. It currently supports
-all calls except credentials.
-
-Usage - DomainKeys
------------------------
-First, instantiate the Mailgun Client with your API key
-```ruby
-mg_client = Mailgun::Client.new('your-api-key')
-domainer = Mailgun::DomainKeys.new(mg_client)
-```
-
-Domain Keys methods:
-
-```ruby
-# List keys for all domains
-domainer.list_domain_keys { some: 'options' }
-
-# Create a domain key
-domainer.create_domain_key { some: 'options' }
-
-# Delete a domain key
-domainer.delete_domain_key { some: 'options' }
-
-# Activate a domain key
-domainer.activate_domain_key 'my.perfect.domain', 'selector'
-
-# List domain keys
-domainer.get_domain_keys 'my.perfect.domain'
-
-# Deactivate a domain key
-domainer.deactivate_domain_key 'my.perfect.domain', 'selector'
-
-# Update DKIM authority
-domainer.update_domain_dkim_authority 'my.perfect.domain', { some: 'options' }
-
-# Update a DKIM selector
-domainer.update_domain_dkim_selector 'my.perfect.domain', { some: 'options' }
-```
-
-More Documentation
-------------------
-See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys)
-for more information

data/docs/Domains.md

@@ -1,82 +0,0 @@
-Mailgun - Domains
-====================
-
-This is the Mailgun Ruby *Domain* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions. It currently supports
-all calls except credentials.
-
-Usage - Domains
------------------------
-First, instantiate the Mailgun Client with your API key
-```ruby
-mg_client = Mailgun::Client.new('your-api-key')
-domainer = Mailgun::Domains.new(mg_client)
-```
-
-Core Domain methods:
-
-```ruby
-# Get a list of current domains.
-domainer.list
-
-# Add a new domain
-domainer.create 'my.new.moreness'
-# or with options
-domainer.create 'my.new.moreness', { some: 'options' }
-
-# View details of a domain
-domainer.get 'my.perfect.domain'
-
-# Update a domain
-domainer.update 'my.new.moreness', { some: 'options' }
-
-# Verify a domain
-domainer.verify 'my.perfect.domain'
-
-# Remove a domain
-domainer.remove 'this.one.is.not.needed.'
-
-
-```
-
-Domain Tracking methods:
-
-```ruby
-# Get tracking settings
-domainer.get_domain_tracking_settings 'my.perfect.domain'
-
-# Update click tracking settings
-domainer.update_domain_tracking_click_settings 'my.perfect.domain', { some: 'options' }
-
-# Update open tracking settings
-domainer.update_domain_tracking_open_settings 'my.perfect.domain', { some: 'options' }
-
-# Update unsubscribe tracking settings
-domainer.update_domain_tracking_unsubscribe_settings  'my.perfect.domain', { some: 'options' }
-
-# Tracking Certificate: Get certificate and status
-domainer.get_domain_tracking_certificate 'my.perfect.domain'
-
-# Tracking Certificate: Regenerate expired certificate
-domainer.regenerate_domain_tracking_certificate 'my.perfect.domain', { some: 'options' }
-
-# Tracking Certificate: Generate
-domainer.generate_domain_tracking_certificate 'my.perfect.domain', { some: 'options' }
-```
-
-DKIM Security methods:
-
-```ruby
-# Update Automatic Sender Security DKIM key rotation for a domain
-domainer.dkim_rotation 'my.perfect.domain', true, { some: 'options' }
-
-# Rotate Automatic Sender Security DKIM key for a domain
-domainer.dkim_rotate 'my.perfect.domain'
-```
-
-More Documentation
-------------------
-See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains)
-for more information

data/docs/EmailValidation.md

@@ -1,34 +0,0 @@
-Mailgun - Email Validation
-====================
-
-This is the Mailgun Ruby *Email Validation* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions.
-
-Usage - Email Validation
------------------------
-
-```ruby
-# First, instantiate the Mailgun Address. It pulls api key for Client from Mailgun.api_key variable.
-email_validator = Mailgun::Address.new
-
-# Given an arbitrary address, validates address based off defined checks.
-# Response Example:
-# {
-#     "address": "existingemail@realdomain.com",
-#     "is_disposable_address": false,
-#     "is_role_address": false,
-#     "reason": [],
-#     "result": "deliverable",
-#     "risk": "low"
-# }
-email_validator.validate('email@example.com')
-
-
-```
-
-More Documentation
-------------------
-See the official [Mailgun Email Validation Docs](https://documentation.mailgun.com/en/latest/api-email-validation.html)
-for more information

data/docs/Events.md

@@ -1,48 +0,0 @@
-Mailgun - Events
-====================
-
-_WARNING: This API is deprecated in favor of our Logs API._
-
-This is the Mailgun Ruby *Events* utility.
-
-The below assumes you've already installed the Mailgun Ruby SDK in your project.
-If not, go back to the master README for a few quick install steps.
-
-Events: Provides methods for traversing the Mailgun Events API.
-
-
-Usage - Events
------------------------------------------------------
-Here's how to use the Events Handler to pull events.
-
-```ruby
-# First, instantiate the SDK with your API credentials, domain, and required parameters for example.
-mg_client = Mailgun::Client.new("your-api-key")
-mg_events = Mailgun::Events.new(mg_client, "your-domain")
-
-result = mg_events.get({'limit' => 25,
-                        'recipient' => 'joe@example.com'})
-
-result.to_h['items'].each do | item |
-    # outputs "Delivered - 20140509184016.12571.48844@example.com"
-    puts "#{item['event']} - #{item['message']['headers']['message-id']}"
-end
-
-# Want more results?
-result = mg_events.next
-
-# Go backwards?
-result = mg_events.previous
-```
-
-A few notes:  
-1. Next will use the pagination links to advance the result set.
-Retain the mg_events object to query forward, or reverse, at any time.  
-2. If the result set is less than your limit, do not worry. A
-second query against "next" will return the next 25 results since the
-last time you called "next".
-
-More Documentation
-------------------
-See the official [Mailgun Docs](https://documentation.mailgun.com/en/latest/api-events.html)
-for more information.

data/docs/Logs.md

@@ -1,67 +0,0 @@
-Mailgun - Logs
-====================
-
-This is the Mailgun Ruby *Logs* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions. It currently supports
-all calls except credentials.
-
----
-
-Mailgun collects many different events and generates event logs which are available
-in your Control Panel. This data is also available via our analytics logs API endpoint.
-
-You can view additional samples in the [logs_spec.rb](/spec/integration/logs_spec.rb)
-or the Logs client API in [logs.rb](/lib/logs/logs.rb).
-
-Usage
------
-
-To get an instance of the Logs client:
-
-```ruby
-require 'mailgun'
-
-mg_client = Mailgun::Client.new('your-api-key', 'mailgun-api-host', 'v1')
-logs = Mailgun::Logs.new(mg_client)
-````
----
-Get filtered logs for an account:
-```ruby
-options = {
-  {
-    start: 'Mon, 08 Jul 2024 00:00:00 -0000',
-    end: 'Fri, 12 Jul 2024 00:00:00 -0000',
-    filter: {
-      AND: [
-        {
-          attribute: 'domain',
-          comparator: '=',
-          values: [
-            {
-              label: 'example.com',
-              value: 'example.com'
-            }
-          ]
-        }
-      ]
-    },
-    include_subaccounts: true,
-    pagination: {
-      sort: 'timestamp:asc',
-      token: 'cjsijbijewbu78t678tVTYUYU76754fyuiksin865g',
-      limit: 50
-    }
-  }
-}
-
-logs.account_logs(options)
-```
-
----
-
-More Documentation
-------------------
-See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Logs/)
-for more information

data/docs/MessageBuilder.md

@@ -1,120 +0,0 @@
-Mailgun - Messages
-====================
-
-This is the Mailgun Ruby *Message* utilities.
-
-The below assumes you've already installed the Mailgun Gem. If not, go back to the master README for instructions.
-
-There are two utilities included, Message Builder and Batch Message.
-
-Message Builder: Allows you to build a message object by calling methods for
-each attribute.
-Batch Message: Inherits Message Builder and allows you to iterate through
-recipients from a list. Messages will fire after the 1,000th recipient has been
-added.
-
-Usage - Message Builder
------------------------
-Here's how to use Message Builder to build your Message.
-
-```ruby
-# First, instantiate the Mailgun Client with your API key
-mg_client = Mailgun::Client.new("your-api-key")
-mb_obj = Mailgun::MessageBuilder.new()
-
-# Define the from address.
-mb_obj.from("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
-
-# Define a to recipient.
-mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John", "last" => "Doe"});
-
-# Define a cc recipient.
-mb_obj.add_recipient(:cc, "sally.doe@example.com", {"first" => "Sally", "last" => "Doe"});
-
-# Define the reply-to address.
-mb_obj.reply_to("bob.doe@example.com", {"first" => "Bob", "last" => "Doe"});
-
-# Define the subject.
-mb_obj.subject("A message from the Ruby SDK using Message Builder!");
-
-# Define the body of the message.
-mb_obj.body_text("This is the text body of the message!");
-
-# Define the HTML text of the message
-mb_obj.body_html("<html><body><p>This is the text body of the message</p></body></html>");
-
-# Set the Message-Id header, provide a valid Message-Id.
-mb_obj.message_id("<20141014000000.11111.11111@example.com>")
-
-# Or clear the Message-Id header, provide nil or empty string.
-mb_obj.message_id(nil)
-mb_obj.message_id('')
-
-# Set the Message-tags at most 10.
-mb_obj.add_tag("You can track mails as tag-units!")
-
-# Campaigns and headers.
-mb_obj.add_campaign_id("My-Awesome-Campaign");
-mb_obj.header("Customer-Id", "12345");
-
-# Custom variables
-mb_obj.variable("Customer-Data", { :first_name => "John", :last_name => "Smith" })
-
-# Attach a file and rename it.
-mb_obj.add_attachment "/path/to/file/receipt_123491820.pdf", "Receipt.pdf"
-
-# Attach an image inline.
-mb_obj.add_inline_image "/path/to/file/header.png"
-
-# Schedule message in the future
-mb_obj.deliver_at("tomorrow 8:00AM PST");
-
-# Turn Click Tracking on
-mb_obj.track_clicks(true)
-
-# Turn Click Tracking off
-mb_obj.track_clicks(false)
-
-# Finally, send your message using the client
-result = mg_client.send_message("sending_domain.com", mb_obj)
-
-puts result.body.to_s
-```
-
-Usage - Batch Message
----------------------
-Here's how to use Batch Message to easily handle batch sending jobs.
-
-```ruby
-# First, instantiate the Mailgun Client with your API key
-mg_client = Mailgun::Client.new("your-api-key")
-
-# Create a Batch Message object, pass in the client and your domain.
-mb_obj = Mailgun::BatchMessage.new(mg_client, "example.com")
-
-# Define the from address.
-mb_obj.from("me@example.com", {"first" => "Ruby", "last" => "SDK"});
-
-# Define the subject.
-mb_obj.subject("A message from the Ruby SDK using Message Builder!");
-
-# Define the body of the message.
-mb_obj.body_text("This is the text body of the message!");
-
-
-# Loop through all of your recipients
-mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John", "last" => "Doe"});
-mb_obj.add_recipient(:to, "jane.doe@example.com", {"first" => "Jane", "last" => "Doe"});
-mb_obj.add_recipient(:to, "bob.doe@example.com", {"first" => "Bob", "last" => "Doe"});
-...
-mb_obj.add_recipient(:to, "sally.doe@example.com", {"first" => "Sally", "last" => "Doe"});
-
-# Call finalize to get a list of message ids and totals.
-message_ids = mb_obj.finalize
-# {'id1234@example.com' => 1000, 'id5678@example.com' => 15}
-```
-
-More Documentation
-------------------
-See the official [Mailgun Docs](https://documentation.mailgun.com/en/latest/api-sending.html)
-for more information.

data/docs/Metrics.md

@@ -1,108 +0,0 @@
-Mailgun - Metrics
-====================
-
-This is the Mailgun Ruby *Metrics* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions. It currently supports
-all calls except credentials.
-
----
-
-Mailgun collects many different events and generates event metrics which are available
-in your Control Panel. This data is also available via our analytics metrics API endpoint.
-
-You can view additional samples in the [metrics_spec.rb](/spec/integration/metrics_spec.rb)
-or the Metrics client API in [metrics.rb](/lib/metrics/metrics.rb).
-
-Usage
------
-
-To get an instance of the Metrics client:
-
-```ruby
-require 'mailgun'
-
-mg_client = Mailgun::Client.new('your-api-key', 'mailgun-api-host', 'v1')
-metrics = Mailgun::Metrics.new(mg_client)
-````
----
-Get filtered metrics for an account:
-```ruby
-options = {
-  {
-    resolution: 'hour',
-    metrics: [
-      'accepted_count',
-      'delivered_count',
-      'clicked_rate',
-      'opened_rate'
-    ],
-    include_aggregates: true,
-    start: 'Tue, 26 Nov 2024 20:56:50 -0500',
-    duration: '1m',
-    filter: {
-      AND: [
-        {
-          attribute: 'domain',
-          comparator: '!=',
-          values: [
-            {
-              label: 'example.com',
-              value: 'example.com'
-            }
-          ]
-        }
-      ]
-    },
-    dimensions: ['time'],
-    end: 'Tue, 30 Nov 2024 20:56:50 -0500',
-    include_subaccounts: true
-  }
-}
-
-metrics.account_metrics(options)
-```
----
-
-Get filtered usage metrics for an account:
-```ruby
-options = {
-  resolution: 'hour',
-  metrics: [
-    'accepted_count',
-    'delivered_count',
-    'clicked_rate',
-    'opened_rate'
-  ],
-  include_aggregates: true,
-  start: 'Tue, 26 Nov 2024 20:56:50 -0500',
-  duration: '1m',
-  filter: {
-    AND: [
-      {
-        attribute: 'domain',
-        comparator: '!=',
-        values: [
-          {
-            label: 'example.com',
-            value: 'example.com'
-          }
-        ]
-      }
-    ]
-  },
-  dimensions: ['time'],
-  end: 'Tue, 30 Nov 2024 20:56:50 -0500',
-  include_subaccounts: true
-}
-
-metrics.account_usage_metrics(options)
-```
-
----
-
-More Documentation
-------------------
-See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Metrics/)
-for more information

data/docs/OptInHandler.md

@@ -1,103 +0,0 @@
-Mailgun - Lists
-====================
-
-This is the Mailgun Ruby *Lists* utilities.
-
-The below assumes you've already installed the Mailgun Ruby SDK in your project.
-If not, go back to the master README for a few quick install steps.
-
-OptInHandler: Provides methods for authenticating an Opt-In Request.
-
-The typical flow for using this utility would be as follows:
-**Recipient Requests Subscribe** -> [Validate Recipient Address] -> [Generate Opt-In Link] -> [Email Recipient Opt-In Link]
-**Recipient Clicks Opt-In Link** -> [Validate Opt-In Link] -> [Subscribe User] -> [Send final confirmation]
-
-The above flow is modeled below.
-
-Usage - Opt-In Handler (Recipient Requests Subscribe)
------------------------------------------------------
-Here's how to use Opt-In Handler to validate Opt-In requests.
-
-```ruby
-# First, instantiate the SDK with your API credentials, domain, and required parameters for example.
-mg_client = Mailgun::Client.new("your-api-key")
-mg_validate = Mailgun::Client.new("your-pub-api-key")
-
-domain = 'example.com';
-
-mailing_list = 'youlist@example.com';
-secret_app_id = 'a_secret_passphrase';
-recipient_address = 'recipient@example.com';
-
-# Let's validate the customer's email address, using Mailgun's validation endpoint.
-result = mg_validate.get('address/validate', {:address => recipient_address});
-body = JSON.parse(result.body)
-
-if body['is_valid'] == true
-	# Next, generate a hash.
-	generated_hash = Mailgun::OptInHandler.generate_hash(mailing_list, secret_app_id, recipient_address);
-	
-	# Now, let's send a confirmation to the recipient with our link.
-	mg_client.send_message(domain, {:from    => 'bob@example.com',
-	                                :to      => recipient_address,
-	                                :subject => 'Please Confirm!',
-	                                :html    => "<html><body>Hello,<br><br>You have requested to be subscribed
-		                            to the mailing list #{mailing_list}. Please <a
-		                            href=\"http://yourdomain.com/subscribe.php?hash=#{generated_hash}\">
-		                            confirm</a> your subscription.<br><br>Thank you!</body></html>"});
-	                                			  
-	# Finally, let's add the subscriber to a Mailing List, as unsubscribed, so we can track non-conversions.
-	mg_client.post("lists/#{mailing_list}/members", {:address    => recipient_address,
-	                                		         :subscribed => 'no',
-	                                			     :upsert     => 'yes'});
-end
-```
-
-Usage - Opt-In Handler (Recipient Clicks Opt In Link)
------------------------------------------------------
-Here's how to use Opt-In Handler to validate an Opt-In Hash.
-
-```ruby
-# First, instantiate the SDK with your API credentials and domain.
-mg_client = Mailgun::Client.new("your-api-key")
-domain = 'example.com';
-
-# Now, validate the captured hash.
-hash_validation = Mailgun::OptInHandler.validate_hash(secret_app_id, inbound_hash);
-
-# Lastly, check to see if we have results, parse, subscribe, and send confirmation.
-if !hash_validation.nil?
-	validated_list = hash_validation['mailing_list'];
-	validated_recipient = hash_validation['recipient_address'];
-	
-	mg_client.put("lists/#{validated_list}/members/#{validated_recipient}",
-							{:address    => validated_recipient,
-	                         :subscribed => 'yes'})
-    
-    mg_client.send_message(domain, {:from    => 'bob@example.com',
-                                    :to      => validated_recipient,
-                                    :subject => 'Confirmation Received!',
-                                    :html    => "<html><body>Hello,<br><br>We've successfully subscribed you to the list, #{validated_list}!<br><br>Thank you!
-                                    </body></html>"});
-end
-```
-
-A few notes:
-1. 'secret_app_id' can be anything. It's used as the *key* in hashing,
-since your email address will vary. It should be secured like a password.
-2. validateHash will return an array containing the recipient address and list
-address.
-3. You should *always* send an email confirmation before and after the
-subscription request. This is what double-opt in means.
-
-
-Available Functions
------------------------------------------------------
-
-`string generate_hash(string mailing_list, string secret_app_id, string recipient_address)`
-
-`array validate_hash(string secret_app_id, string unique_hash)`
-
-More Documentation
-------------------
-See the official [Mailgun Docs](https://documentation.mailgun.com/) for more information.