class Mailgun::Suppressions

The Mailgun::Suppressions object makes it easy to manage “suppressions” attached to an account. “Suppressions” means bounces, unsubscribes, and complaints.

Public Class Methods

new(client, domain) click to toggle source

@param [Mailgun::Client] client API client to use for requests @param [String] domain Domain name to use for the suppression endpoints.

# File lib/mailgun/suppressions.rb, line 13
def initialize(client, domain)
  @client = client
  @domain = domain

  @paging_next = nil
  @paging_prev = nil
end

Public Instance Methods

create_bounce(params = {}) click to toggle source
# File lib/mailgun/suppressions.rb, line 51
def create_bounce(params = {})
  @client.post("#{@domain/bounces}", params)
end
create_bounces(data) click to toggle source

Creates multiple bounces on the Mailgun API. If a bounce does not have a valid structure, it will be added to a list of unsendable bounces. The list of unsendable bounces will be returned at the end of this operation.

If more than 999 bounce entries are provided, the list will be split and recursive calls will be made.

@param [Array] data Array of bounce hashes @return [Response] Mailgun API response @return [Array] Return values from recursive call for list split.

# File lib/mailgun/suppressions.rb, line 64
def create_bounces(data)
  # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
  split_return = []
  if data.length >= 1000 then
    resp, resp_l = create_bounces data[999..-1]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.length == 0 then
    return nil, []
  end

  valid = []
  # Validate the bounces given
  # NOTE: `data` could potentially be very large (1000 elements) so it is
  # more efficient to pop from data and push into a different array as
  # opposed to possibly copying the entire array to another array.
  while not data.empty? do
    bounce = data.pop
    # Bounces MUST contain a `address` key.
    if not bounce.include? :address then
      raise Mailgun::ParameterError.new "Bounce MUST include a :address key: #{bounce}"
    end

    bounce.each do |k, v|
      # Hash values MUST be strings.
      if not v.is_a? String then
        bounce[k] = v.to_s
      end
    end

    valid.push bounce
  end

  response = @client.post("#{@domain}/bounces", valid.to_json, { "Content-Type" => "application/json" })
  return response, split_return
end
create_complaint(params = {}) click to toggle source
# File lib/mailgun/suppressions.rb, line 193
def create_complaint(params = {})
  @client.post("#{@domain}/complaints", params)
end
create_complaints(data) click to toggle source

Creates multiple complaints on the Mailgun API. If a complaint does not have a valid structure, it will be added to a list of unsendable complaints. The list of unsendable complaints will be returned at the end of this operation.

If more than 999 complaint entries are provided, the list will be split and recursive calls will be made.

@param [Array] data Array of complaint hashes @return [Response] Mailgun API response @return [Array] Return values from recursive call for list split.

# File lib/mailgun/suppressions.rb, line 206
def create_complaints(data)
  # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
  split_return = []
  if data.length >= 1000 then
    resp, resp_l = create_complaints data[999..-1]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.length == 0 then
    return nil, []
  end

  valid = []
  # Validate the complaints given
  while not data.empty? do
    complaint = data.pop
    # complaints MUST contain a `address` key.
    if not complaint.include? :address then
      raise Mailgun::ParameterError.new "Complaint MUST include a :address key: #{complaint}"
    end

    complaint.each do |k, v|
      # Hash values MUST be strings.
      if not v.is_a? String then
        complaint[k] = v.to_s
      end
    end

    valid.push complaint
  end

  response = @client.post("#{@domain}/complaints", valid.to_json, { "Content-Type" => "application/json" })
  return response, split_return
end
create_unsubscribe(params = {}) click to toggle source
# File lib/mailgun/suppressions.rb, line 124
def create_unsubscribe(params = {})
  @client.post("#{@domain}/unsubscribes", params)
end
create_unsubscribes(data) click to toggle source

Creates multiple unsubscribes on the Mailgun API. If an unsubscribe does not have a valid structure, it will be added to a list of unsendable unsubscribes. The list of unsendable unsubscribes will be returned at the end of this operation.

If more than 999 unsubscribe entries are provided, the list will be split and recursive calls will be made.

@param [Array] data Array of unsubscribe hashes @return [Response] Mailgun API response @return [Array] Return values from recursive call for list split.

# File lib/mailgun/suppressions.rb, line 137
def create_unsubscribes(data)
  # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
  split_return = []
  if data.length >= 1000 then
    resp, resp_l = create_unsubscribes data[999..-1]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.length == 0 then
    return nil, []
  end

  valid = []
  # Validate the unsubscribes given
  while not data.empty? do
    unsubscribe = data.pop
    # unsubscribes MUST contain a `address` key.
    if not unsubscribe.include? :address then
      raise Mailgun::ParameterError.new "Unsubscribe MUST include a :address key: #{unsubscribe}"
    end

    unsubscribe.each do |k, v|
      # Hash values MUST be strings.
      # However, unsubscribes contain an array of tags
      if v.is_a? Array
        unsubscribe[k] = v.map(&:to_s)
      elsif !v.is_a? String
        unsubscribe[k] = v.to_s
      end
    end

    valid.push unsubscribe
  end

  response = @client.post("#{@domain}/unsubscribes", valid.to_json, { "Content-Type" => "application/json" })
  return response, split_return
end
delete_all_bounces() click to toggle source
# File lib/mailgun/suppressions.rb, line 106
def delete_all_bounces
  @client.delete("#{@domain}/bounces")
end
delete_bounce(address) click to toggle source
# File lib/mailgun/suppressions.rb, line 102
def delete_bounce(address)
  @client.delete("#{@domain}/bounces/#{address}")
end
delete_complaint(address) click to toggle source
# File lib/mailgun/suppressions.rb, line 241
def delete_complaint(address)
  @client.delete("#{@domain}/complaints/#{address}")
end
delete_unsubscribe(address, params = {}) click to toggle source
# File lib/mailgun/suppressions.rb, line 175
def delete_unsubscribe(address, params = {})
  @client.delete("#{@domain}/unsubscribes/#{address}")
end
get_bounce(address) click to toggle source
# File lib/mailgun/suppressions.rb, line 47
def get_bounce(address)
  @client.get("#{@domain}/bounces/#{address}", nil)
end
get_complaint(address) click to toggle source
# File lib/mailgun/suppressions.rb, line 189
def get_complaint(address)
  @client.get("#{@domain}/complaints/#{address}", nil)
end
get_unsubscribe(address) click to toggle source
# File lib/mailgun/suppressions.rb, line 120
def get_unsubscribe(address)
  @client.get("#{@domain}/unsubscribes/#{address}")
end
list_bounces(params = {}) click to toggle source

Bounces Endpoint (/v3/:domain/bounces)

# File lib/mailgun/suppressions.rb, line 41
def list_bounces(params = {})
  response = @client.get("#{@domain}/bounces", params)
  extract_paging response
  response
end
list_complaints(params = {}) click to toggle source

Complaints Endpoint (/v3/:domain/complaints)

# File lib/mailgun/suppressions.rb, line 183
def list_complaints(params = {})
  response = @client.get("#{@domain}/complaints", params)
  extract_paging response
  response
end
list_unsubscribes(params = {}) click to toggle source

Unsubscribes Endpoint (/v3/:domain/unsubscribes)

# File lib/mailgun/suppressions.rb, line 114
def list_unsubscribes(params = {})
  response = @client.get("#{@domain}/unsubscribes", params)
  extract_paging response
  response
end
next() click to toggle source

Paging operations

# File lib/mailgun/suppressions.rb, line 25
def next
  response = get_from_paging @paging_next[:path], @paging_next[:params]
  extract_paging response
  response
end
prev() click to toggle source
# File lib/mailgun/suppressions.rb, line 31
def prev
  response = get_from_paging @paging_prev[:path], @paging_prev[:params]
  extract_paging response
  response
end

Private Instance Methods

extract_paging(response) click to toggle source
# File lib/mailgun/suppressions.rb, line 251
def extract_paging(response)
  rhash = response.to_h
  return nil unless rhash.include? "paging"

  page_info = rhash["paging"]

  # Build the `next` endpoint
  page_next = URI.parse(page_info["next"])
  @paging_next = {
    :path => page_next.path[/\/v[\d](.+)/, 1],
    :params => Hash[URI.decode_www_form page_next.query],
  }

  # Build the `prev` endpoint
  page_prev = URI.parse(page_info["previous"])
  @paging_prev = {
    :path => page_prev.path[/\/v[\d](.+)/, 1],
    :params => Hash[URI.decode_www_form page_prev.query],
  }
end
get_from_paging(uri, params = {}) click to toggle source
# File lib/mailgun/suppressions.rb, line 247
def get_from_paging(uri, params = {})
  @client.get(uri, params)
end