Class: Mailgun::Suppressions

Inherits:
Object
  • Object
show all
Defined in:
lib/mailgun/suppressions.rb

Overview

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

Instance Method Summary collapse

Constructor Details

#initialize(client, domain) ⇒ Suppressions

Returns a new instance of Suppressions.

Parameters:

  • client (Mailgun::Client) —

    API client to use for requests

  • domain (String) —

    Domain name to use for the suppression endpoints.



9
10
11
12
13
14
15
 
# File 'lib/mailgun/suppressions.rb', line 9

def initialize(client, domain)
  @client = client
  @domain = domain

  @paging_next = nil
  @paging_prev = nil
end

Instance Method Details

#create_bounce(params = {}) ⇒ Object 



47
48
49
 
# File 'lib/mailgun/suppressions.rb', line 47

def create_bounce(params = {})
  @client.post("#{@domain}/bounces", params)
end

#create_bounces(data) ⇒ Response, Array

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.

Parameters:

  • data (Array) —

    Array of bounce hashes

Returns:

  • (Response) —

    Mailgun API response

  • (Array) —

    Return values from recursive call for list split.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/mailgun/suppressions.rb', line 60

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
    resp, resp_l = create_bounces data[999..]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.empty?
    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.
  until data.empty?
    bounce = data.pop
    # Bounces MUST contain a `address` key.
    raise Mailgun::ParameterError, "Bounce MUST include a :address key: #{bounce}" unless bounce.include? :address

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

    valid.push bounce
  end

  response = @client.post("#{@domain}/bounces", valid.to_json, { 'Content-Type' => 'application/json' })
  [response, split_return]
end

#create_complaint(params = {}) ⇒ Object 



185
186
187
 
# File 'lib/mailgun/suppressions.rb', line 185

def create_complaint(params = {})
  @client.post("#{@domain}/complaints", params)
end

#create_complaints(data) ⇒ Response, Array

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.

Parameters:

  • data (Array) —

    Array of complaint hashes

Returns:

  • (Response) —

    Mailgun API response

  • (Array) —

    Return values from recursive call for list split.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/mailgun/suppressions.rb', line 198

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
    resp, resp_l = create_complaints data[999..]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.empty?
    return nil, []
  end

  valid = []
  # Validate the complaints given
  until data.empty?
    complaint = data.pop
    # complaints MUST contain a `address` key.
    unless complaint.include? :address
      raise Mailgun::ParameterError, "Complaint MUST include a :address key: #{complaint}"
    end

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

    valid.push complaint
  end

  response = @client.post("#{@domain}/complaints", valid.to_json, { 'Content-Type' => 'application/json' })
  [response, split_return]
end

#create_unsubscribe(params = {}) ⇒ Object 



116
117
118
 
# File 'lib/mailgun/suppressions.rb', line 116

def create_unsubscribe(params = {})
  @client.post("#{@domain}/unsubscribes", params)
end

#create_unsubscribes(data) ⇒ Response, Array

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.

Parameters:

  • data (Array) —

    Array of unsubscribe hashes

Returns:

  • (Response) —

    Mailgun API response

  • (Array) —

    Return values from recursive call for list split.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/mailgun/suppressions.rb', line 129

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
    resp, resp_l = create_unsubscribes data[999..]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.empty?
    return nil, []
  end

  valid = []
  # Validate the unsubscribes given
  until data.empty?
    unsubscribe = data.pop
    # unsubscribes MUST contain a `address` key.
    unless unsubscribe.include? :address
      raise Mailgun::ParameterError, "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' })
  [response, split_return]
end

#delete_all_bounces ⇒ Object 



98
99
100
 
# File 'lib/mailgun/suppressions.rb', line 98

def delete_all_bounces
  @client.delete("#{@domain}/bounces")
end

#delete_bounce(address) ⇒ Object 



94
95
96
 
# File 'lib/mailgun/suppressions.rb', line 94

def delete_bounce(address)
  @client.delete("#{@domain}/bounces/#{escape_address(address)}")
end

#delete_complaint(address) ⇒ Object 



231
232
233
 
# File 'lib/mailgun/suppressions.rb', line 231

def delete_complaint(address)
  @client.delete("#{@domain}/complaints/#{escape_address(address)}")
end

#delete_unsubscribe(address, _params = {}) ⇒ Object 



167
168
169
 
# File 'lib/mailgun/suppressions.rb', line 167

def delete_unsubscribe(address, _params = {})
  @client.delete("#{@domain}/unsubscribes/#{escape_address(address)}")
end

#get_bounce(address) ⇒ Object 



43
44
45
 
# File 'lib/mailgun/suppressions.rb', line 43

def get_bounce(address)
  @client.get("#{@domain}/bounces/#{escape_address(address)}")
end

#get_complaint(address) ⇒ Object 



181
182
183
 
# File 'lib/mailgun/suppressions.rb', line 181

def get_complaint(address)
  @client.get("#{@domain}/complaints/#{escape_address(address)}")
end

#get_unsubscribe(address) ⇒ Object 



112
113
114
 
# File 'lib/mailgun/suppressions.rb', line 112

def get_unsubscribe(address)
  @client.get("#{@domain}/unsubscribes/#{escape_address(address)}")
end

#list_bounces(params = {}) ⇒ Object

Bounces Endpoint (/v3/:domain/bounces)



37
38
39
40
41
 
# File 'lib/mailgun/suppressions.rb', line 37

def list_bounces(params = {})
  response = @client.get("#{@domain}/bounces", params)
  extract_paging response
  response
end

#list_complaints(params = {}) ⇒ Object

Complaints Endpoint (/v3/:domain/complaints)



175
176
177
178
179
 
# File 'lib/mailgun/suppressions.rb', line 175

def list_complaints(params = {})
  response = @client.get("#{@domain}/complaints", params)
  extract_paging response
  response
end

#list_unsubscribes(params = {}) ⇒ Object

Unsubscribes Endpoint (/v3/:domain/unsubscribes)



106
107
108
109
110
 
# File 'lib/mailgun/suppressions.rb', line 106

def list_unsubscribes(params = {})
  response = @client.get("#{@domain}/unsubscribes", params)
  extract_paging response
  response
end

#next ⇒ Object

Paging operations



21
22
23
24
25
 
# File 'lib/mailgun/suppressions.rb', line 21

def next
  response = get_from_paging @paging_next[:path], @paging_next[:params]
  extract_paging response
  response
end

#prev ⇒ Object 



27
28
29
30
31
 
# File 'lib/mailgun/suppressions.rb', line 27

def prev
  response = get_from_paging @paging_prev[:path], @paging_prev[:params]
  extract_paging response
  response
end