Class: Mailgun::Domains

Inherits:
Object
  • Object
show all
Includes:
ApiVersionChecker
Defined in:
lib/mailgun/domains/domains.rb

Overview

A Mailgun::Domains object is a simple CRUD interface to Mailgun Domains. Uses Mailgun

Instance Method Summary collapse

Methods included from ApiVersionChecker

included

Constructor Details

#initialize(client = Mailgun::Client.new) ⇒ Domains

Public: creates a new Mailgun::Domains instance.

Defaults to Mailgun::Client



10
11
12
 
# File 'lib/mailgun/domains/domains.rb', line 10

def initialize(client = Mailgun::Client.new)
  @client = client
end

Instance Method Details

#activate_domain_key(domain, selector) ⇒ Object

Public: Activate a domain key for a specified authority and selector.

domain - [String] Name of the domain (ex. domain.com) selector - [String] The selector you want to activate for the domain key

Returns [Hash] with message key and autority + selector data



137
138
139
 
# File 'lib/mailgun/domains/domains.rb', line 137

def activate_domain_key(domain, selector)
  @client.put("domains/#{domain}/keys/#{selector}/activate", {}).to_h
end

#create(domain, options = {}) ⇒ Object

Public: Add domain

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

smtp_password - [String] Password for SMTP authentication
spam_action   - [String] disabled, blocked or tag
  Disable, no spam filtering will occur for inbound messages.
  Block, inbound spam messages will not be delivered.
  Tag, messages will be tagged with a spam header. See Spam Filter.
wildcard      - [Boolean] true or false Determines whether the domain will accept email for sub-domains.

Returns [Hash] of created domain



38
39
40
41
42
 
# File 'lib/mailgun/domains/domains.rb', line 38

def create(domain, options = {})
  options = { smtp_password: nil, spam_action: 'disabled', wildcard: false }.merge(options)
  options[:name] = domain
  @client.post('domains', options).to_h
end

#create_domain_key(options = {}) ⇒ Object

Public: Create a domain key

options - [Hash] of

signing_domain  - [String] Name of the domain (ex. domain.com)
selector - [String] Selector to be used for the new domain key
bits - [Integer] Key size, can be 1024 or 2048
pem - [String] Private key PEM

Returns [Hash] with message key



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

def create_domain_key(options = {})
  @client.post("dkim/keys", options).to_h
end

#create_smtp_credentials(domain, options = {}) ⇒ Object

Public: Creates a new set of SMTP credentials for the defined domain.

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

login  - [String] The user name (ex. bob.bar)
password  - [String] A password for the SMTP credentials. (Length Min 5, Max 32)

Returns [Hash] with message key



299
300
301
 
# File 'lib/mailgun/domains/domains.rb', line 299

def create_smtp_credentials(domain, options = {})
  @client.post("domains/#{domain}/credentials", options).to_h
end

#deactivate_domain_key(domain, selector) ⇒ Object

Public: Deactivate a domain key for a specified authority and selector

domain - [String] Name of the domain (ex. domain.com) selector - [String] The selector you want to activate for the domain key

Returns [Hash] with message key and autority + selector data



156
157
158
 
# File 'lib/mailgun/domains/domains.rb', line 156

def deactivate_domain_key(domain, selector)
  @client.put("domains/#{domain}/keys/#{selector}/deactivate", {}).to_h
end

#delete_domain_key(options = {}) ⇒ Object

Public: Delete a domain key.

options - [Hash] of

signing_domain - [Integer] Name of the domain (ex. domain.com)
selector - [String] Name of the selector

Returns [Hash] with message key



127
128
129
 
# File 'lib/mailgun/domains/domains.rb', line 127

def delete_domain_key(options = {})
  @client.delete("dkim/keys", options).to_h
end

#delete_smtp_credentials(domain, login) ⇒ Object

Public: Deletes the defined SMTP credentials.

domain - [String] Name of the domain (ex. domain.com) login - [String] The user name (ex. bob.bar)

Returns [Hash] with message and spec keys



321
322
323
 
# File 'lib/mailgun/domains/domains.rb', line 321

def delete_smtp_credentials(domain, )
  @client.delete("domains/#{domain}/credentials/#{}").to_h
end

#dkim_rotate(domain) ⇒ Object

Public: Rotate Automatic Sender Security DKIM key for a domain

domain - [String] The Domain name

Returns [Hash] Response message



283
284
285
 
# File 'lib/mailgun/domains/domains.rb', line 283

def dkim_rotate(domain)
  @client.post("dkim_management/domains/#{domain}/rotate", {})
end

#dkim_rotation(domain, rotation_enabled, options = {}) ⇒ Object

Public: Tracking Certificate: Generate

domain - [String] The Domain name rotation_enabled - [Boolean] If true, enables DKIM Auto-Rotation. If false, disables it

options - [Hash] of

rotation_interval - [String] The interval at which to rotate keys. Example, '5d' for five days

Returns [Hash] domain object



273
274
275
276
 
# File 'lib/mailgun/domains/domains.rb', line 273

def dkim_rotation(domain, rotation_enabled, options = {})
  options = { rotation_enabled: rotation_enabled }.merge(options)
  @client.put("dkim_management/domains/#{domain}/rotation", options)
end

#generate_domain_tracking_certificate(domain, options = {}) ⇒ Object

Public: Tracking Certificate: Generate

domain - [String] The tracking domain of the TLS certificate, formatted as web_prefix.domain_name

Returns [Hash] A message indicating the status of the request.



255
256
257
 
# File 'lib/mailgun/domains/domains.rb', line 255

def generate_domain_tracking_certificate(domain, options = {})
  @client.post("x509/#{domain}", options).to_h
end

#get(domain) ⇒ Object

Public: Get domain information

domain - [String] Domain name to lookup

Returns [Hash] Information on the requested domains.



49
50
51
 
# File 'lib/mailgun/domains/domains.rb', line 49

def get(domain)
  @client.get("domains/#{domain}").to_h!
end

#get_domain_keys(domain) ⇒ Object

Public: Lists the domain keys for a specified signing domain / authority

domain - [String] Name of the domain (ex. domain.com)

Returns [Hash] with domain keys data



146
147
148
 
# File 'lib/mailgun/domains/domains.rb', line 146

def get_domain_keys(domain)
  @client.get("domains/#{domain}/keys").to_h
end

#get_domain_stats(domain, options = {}) ⇒ Object

Public: Returns total stats for a given domains

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

event - [String] The type of the event.
start - [String] The starting time. Should be in RFC 2822 or unix epoch format.
end - [String] The ending date. Should be in RFC 2822 or unix epoch format
resolution - [String] Can be either hour, day or month. Default: day
duration - [String] Period of time with resoluton encoded

Returns [Array] A list of domains (hash)



340
341
342
343
 
# File 'lib/mailgun/domains/domains.rb', line 340

def get_domain_stats(domain, options = {})
  fail(ParameterError, 'No domain given to list stats on Mailgun', caller) unless domain
  @client.get("#{domain}/stats/total", options).to_h
end

#get_domain_tracking_certificate(domain) ⇒ Object

Public: Tracking Certificate: Get certificate and status

domain - [String] The tracking domain of the TLS certificate, formatted as web_prefix.domain_name

Returns [Hash] Status of certificate. Either ‘expired’ ‘processing’ ‘active’ or ‘error’



237
238
239
 
# File 'lib/mailgun/domains/domains.rb', line 237

def get_domain_tracking_certificate(domain)
  @client.get("x509/#{domain}/status").to_h
end

#get_domain_tracking_settings(domain) ⇒ Object

Public: Returns tracking settings for the defined domain.

domain - [String] Name of the domain (ex. domain.com)

Returns [Hash] Information on the tracking settings



192
193
194
 
# File 'lib/mailgun/domains/domains.rb', line 192

def get_domain_tracking_settings(domain)
  @client.get("domains/#{domain}/tracking").to_h
end

#list(options = {}) ⇒ Object

Public: Get Domains

limit - [Integer] Maximum number of records to return. (100 by default) skip - [Integer] Number of records to skip. (0 by default)

Returns [Array] A list of domains (hash)



22
23
24
 
# File 'lib/mailgun/domains/domains.rb', line 22

def list(options = {})
  @client.get('domains', options).to_h['items']
end

#list_domain_keys(options = {}) ⇒ Object

options - [Hash] of

page - [String] Encoded paging information, provided via 'next', 'previous' links
limit - [Integer] Limits the number of items returned in a request
signing_domain  - [String] Filter by signing domain
selector - [String] Filter by selector

Returns [Hash] with message key



103
104
105
 
# File 'lib/mailgun/domains/domains.rb', line 103

def list_domain_keys(options = {})
  @client.get("dkim/keys", options).to_h
end

#regenerate_domain_tracking_certificate(domain, options = {}) ⇒ Object

Tracking Certificate: Regenerate expired certificate

domain - [String] The tracking domain of the TLS certificate, formatted as web_prefix.domain_name

Returns [Hash] A message indicating the status of the request.



246
247
248
 
# File 'lib/mailgun/domains/domains.rb', line 246

def regenerate_domain_tracking_certificate(domain, options = {})
  @client.put("x509/#{domain}", options).to_h
end

#remove(domain) ⇒ Object

Public: Delete Domain

domain - [String] domain name to delete (ex. domain.com)

Returns [Boolean] if successful or not



85
86
87
 
# File 'lib/mailgun/domains/domains.rb', line 85

def remove(domain)
  @client.delete("domains/#{domain}").to_h['message'] == 'Domain has been deleted'
end

#update(domain, options = {}) ⇒ Object

Public: Update domain

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

spam_action   - [String] disabled, blocked or tag
  Disable, no spam filtering will occur for inbound messages.
  Block, inbound spam messages will not be delivered.
  Tag, messages will be tagged wtih a spam header. See Spam Filter.
web_scheme    - [String] http or https
  Set your open, click and unsubscribe URLs to use http or https
wildcard      - [Boolean] true or false Determines whether the domain will accept email for sub-domains.

Returns [Hash] of updated domain



66
67
68
 
# File 'lib/mailgun/domains/domains.rb', line 66

def update(domain, options = {})
  @client.put("domains/#{domain}", options).to_h
end

#update_domain_dkim_authority(domain, options = {}) ⇒ Object

Public: Change the DKIM authority for a domain.

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

self  - [Boolean] true - the domain will be the DKIM authority for itself even
        if the root domain is registered on the same mailgun account

Returns [Hash] Information on the DKIM authority



168
169
170
 
# File 'lib/mailgun/domains/domains.rb', line 168

def update_domain_dkim_authority(domain, options = {})
  @client.put("domains/#{domain}/dkim_authority", options).to_h
end

#update_domain_dkim_selector(domain, options = {}) ⇒ Object

Public: Update the DKIM selector for a domains

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

dkim_selector  - [String] change the DKIM selector for a domain.

Returns [Hash] with message key



179
180
181
 
# File 'lib/mailgun/domains/domains.rb', line 179

def update_domain_dkim_selector(domain, options = {})
  @client.put("domains/#{domain}/dkim_selector", options).to_h
end

#update_domain_tracking_click_settings(domain, options = {}) ⇒ Object

Public: Updates the click tracking settings for a domain.

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

active  - [Boolean] yes or no. If set to yes, links will be overwritten and pointed to our servers so we can track clicks.

Returns [Hash] Information on the tracking click settings



203
204
205
 
# File 'lib/mailgun/domains/domains.rb', line 203

def update_domain_tracking_click_settings(domain, options = {})
  @client.put("domains/#{domain}/tracking/click", options).to_h
end

#update_domain_tracking_open_settings(domain, options = {}) ⇒ Object

Public: Updates the open tracking settings for a domain.

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

active  - [Boolean] yes or no. If set to yes, a tracking pixel will be inserted below your HTML content.
place_at_the_top  - [Boolean] yes or no. If set to yes, tracking pixel will be moved to top of your HTML content.

Returns [Hash] Information on the tracking open settings



215
216
217
 
# File 'lib/mailgun/domains/domains.rb', line 215

def update_domain_tracking_open_settings(domain, options = {})
  @client.put("domains/#{domain}/tracking/open", options).to_h
end

#update_domain_tracking_unsubscribe_settings(domain, options = {}) ⇒ Object

Public: Updates unsubscribe tracking settings for a domain.

domain - [String] Name of the domain (ex. domain.com) options - [Hash] of

active  - [Boolean] true or false.
html_footer  - [String] Custom HTML version of unsubscribe footer.
text_footer  - [String] Custom text version of unsubscribe footer.

Returns [Hash] Information on the tracking unsubscribe settings



228
229
230
 
# File 'lib/mailgun/domains/domains.rb', line 228

def update_domain_tracking_unsubscribe_settings(domain, options = {})
  @client.put("domains/#{domain}/tracking/unsubscribe", options).to_h
end

#update_smtp_credentials(domain, login, options = {}) ⇒ Object

Public: Updates the specified SMTP credentials.

domain - [String] Name of the domain (ex. domain.com) login - [String] The user name (ex. bob.bar) options - [Hash] of

password  - [String] A password for the SMTP credentials. (Length Min 5, Max 32)

Returns [Hash] with message key



311
312
313
 
# File 'lib/mailgun/domains/domains.rb', line 311

def update_smtp_credentials(domain, , options = {})
  @client.put("domains/#{domain}/credentials/#{}", options).to_h
end

#verify(domain) ⇒ Object

Public: Verify domain

domain - [String] Domain name

Returns [Hash] Information on the updated/verified domains



76
77
78
 
# File 'lib/mailgun/domains/domains.rb', line 76

def verify(domain)
  @client.put("domains/#{domain}/verify", nil).to_h!
end