class Mailgun::Client
See the Github documentation for full examples.
of communicating with our API.
wrapper around RestClient so you don’t have to worry about the HTTP aspect
A Mailgun::Client object is used to communicate with the Mailgun API. It is a
def self.deliveries
-
(Hash)
-
def self.deliveries @@deliveries ||= [] end
def api_version
-
(String)
- client api version
def api_version @api_version end
def communication_error(e)
-
e
(StandardException
) -- upstream exception object
def communication_error(e) if e.respond_to?(:response) && e.response return case e.response_status when Unauthorized::CODE Unauthorized.new(e.message, e.response) when BadRequest::CODE BadRequest.new(e.message, e.response) else CommunicationError.new(e.message, e.response) end end CommunicationError.new(e.message) end
def convert_string_to_file(string)
-
(File)
- File object
Parameters:
-
string
(String
) -- MIME string to post to API
def convert_string_to_file(string) file = Tempfile.new('MG_TMP_MIME') file.write(string) file.rewind file end
def delete(resource_path, params = nil)
-
(Mailgun::Response)
- A Mailgun::Response object.
Parameters:
-
resource_path
(String
) -- This is the API resource you wish to interact
def delete(resource_path, params = nil) if params response = @http_client.delete(resource_path, params: params) else response = @http_client.delete(resource_path) end Response.new(response) rescue => err raise communication_error err end
def disable_test_mode!
Disable test mode
def disable_test_mode! @test_mode = false end
def enable_test_mode!
Enable test mode
def enable_test_mode! @test_mode = true end
def endpoint_generator(api_host, api_version, ssl)
-
(string)
- concatenated URL string
Parameters:
-
ssl
(Boolean
) -- True, SSL. False, No SSL. -
api_version
(String
) -- The version of the API to hit -
api_host
(String
) -- URL endpoint the library will hit
def endpoint_generator(api_host, api_version, ssl) ssl ? scheme = 'https' : scheme = 'http' if api_version "#{scheme}://#{api_host}/#{api_version}" else "#{scheme}://#{api_host}" end end
def get(resource_path, params = {}, accept = '*/*')
-
(CommunicationError)
- If the request fails, raises a communication error.
Returns:
-
(Mailgun::Response)
- A response object containing the API response data.
Parameters:
-
accept
(String
) -- The expected Content-Type of the response. Defaults to '*/*'. -
params
(Hash
) -- Optional request parameters, including query parameters and headers. -
resource_path
(String
) -- The API resource path to request, including the domain if required.
def get(resource_path, params = {}, accept = '*/*') headers = (params[:headers] || {}).merge(accept: accept) response = @http_client.get(resource_path, params, headers) Response.new(response) rescue => err raise communication_error(err) end
def initialize(api_key = Mailgun.api_key,
def initialize(api_key = Mailgun.api_key, api_host = Mailgun.api_host || 'api.mailgun.net', api_version = Mailgun.api_version || 'v3', ssl = true, test_mode = false, timeout = nil, proxy_url = Mailgun.proxy_url) endpoint = endpoint_generator(api_host, api_version, ssl) request_options = { url: endpoint, proxy: Mailgun.proxy_url, ssl: {verify: ssl}, headers: { 'User-Agent' => "mailgun-sdk-ruby/#{Mailgun::VERSION}", 'Accept' =>'*/*' } } request_options.merge!(request: {timeout: timeout}) if timeout @http_client = Faraday.new(request_options) do |conn| conn.request :multipart conn.request :authorization, :basic, 'api', api_key conn.request :url_encoded conn.response :raise_error, include_request: true conn.adapter Faraday.default_adapter conn.options.params_encoder = Faraday::FlatParamsEncoder end @test_mode = test_mode @api_version = api_version end
def perform_data_validation(working_domain, data)
def perform_data_validation(working_domain, data) message = data.respond_to?(:message) ? data.message : data fail ParameterError.new('Missing working domain', working_domain) unless working_domain fail ParameterError.new( 'Missing `to` recipient, message should contain at least 1 recipient', working_domain ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty? fail ParameterError.new( 'Missing a `from` sender, message should contain at least 1 `from` sender', working_domain ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty? end
def post(resource_path, data, headers = {})
-
(Mailgun::Response)
- A Mailgun::Response object.
Parameters:
-
headers
(Hash
) -- Additional headers to pass to the resource. -
data
(Hash
) -- This should be a standard Hash -
resource_path
(String
) -- This is the API resource you wish to interact
def post(resource_path, data, headers = {}) response = @http_client.post(resource_path, data, headers) Response.new(response) rescue => err raise communication_error err end
def put(resource_path, data)
-
(Mailgun::Response)
- A Mailgun::Response object.
Parameters:
-
data
(Hash
) -- This should be a standard Hash -
resource_path
(String
) -- This is the API resource you wish to interact
def put(resource_path, data) response = @http_client.put(resource_path, data) Response.new(response) rescue => err raise communication_error err end
def reset_subaccount
def reset_subaccount @http_client.headers.delete(SUBACCOUNT_HEADER) end
def send_message(working_domain, data)
-
(Mailgun::Response)
- A Mailgun::Response object.
Parameters:
-
data
(Hash
) -- This should be a standard Hash -
working_domain
(String
) -- This is the domain you wish to send from.
def send_message(working_domain, data) perform_data_validation(working_domain, data) if test_mode? then Mailgun::Client.deliveries << data return Response.from_hash( { :body => "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}", :status => 200, } ) end case data when Hash # Remove nil values from the data hash # Submitting nils to the API will likely cause an error. # See also: https://github.com/mailgun/mailgun-ruby/issues/32 data = data.select { |k, v| v != nil } if data.key?(:message) if data[:message].is_a?(String) data[:message] = convert_string_to_file(data[:message]) end return post("#{working_domain}/messages.mime", data) end post("#{working_domain}/messages", data) when MessageBuilder post("#{working_domain}/messages", data.message) else fail ParameterError.new('Unknown data type for data parameter.', data) end end
def set_api_key(api_key)
def set_api_key(api_key) @http_client.set_basic_auth('api', api_key) end
def set_subaccount(subaccount_id)
def set_subaccount(subaccount_id) @http_client.headers = @http_client.headers.merge!({ SUBACCOUNT_HEADER => subaccount_id }) end
def suppressions(domain)
-
(Mailgun::Suppressions)
-
Parameters:
-
domain
(String
) -- Domain which suppressions requests will be made for
def suppressions(domain) Suppressions.new(self, domain) end
def test_mode?
-
(Boolean)
- Is the client set in test mode?
def test_mode? @test_mode end