Class: Mailtrap::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/mailtrap/client.rb

Constant Summary collapse

SENDING_API_HOST = 
'send.api.mailtrap.io'
BULK_SENDING_API_HOST = 
'bulk.api.mailtrap.io'
SANDBOX_API_HOST = 
'sandbox.api.mailtrap.io'
GENERAL_API_HOST = 
'mailtrap.io'
API_PORT = 
443

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: ENV.fetch('MAILTRAP_API_KEY'), api_host: nil, general_api_host: GENERAL_API_HOST, api_port: API_PORT, bulk: false, sandbox: false, inbox_id: nil) ⇒ Client

Initializes a new Mailtrap::Client instance.

Parameters:

  • api_key (String) (defaults to: ENV.fetch('MAILTRAP_API_KEY')) —

    The Mailtrap API key to use for sending. Required. If not set, it is taken from the MAILTRAP_API_KEY environment variable.

  • api_host (String) (defaults to: nil) —

    The Mailtrap API hostname. If not set, it is chosen internally.

  • general_api_host (String) (defaults to: GENERAL_API_HOST) —

    The Mailtrap general API hostname for non-sending operations.

  • api_port (Integer) (defaults to: API_PORT) —

    The Mailtrap API port. Default: 443.

  • bulk (Boolean) (defaults to: false) —

    Whether to use the Mailtrap bulk sending API. Default: false. If enabled, it is incompatible with ‘sandbox: true`.

  • sandbox (Boolean) (defaults to: false) —

    Whether to use the Mailtrap sandbox API. Default: false. If enabled, it is incompatible with ‘bulk: true`.

  • inbox_id (Integer) (defaults to: nil) —

    The sandbox inbox ID to send to. Required if sandbox API is used.

Raises:

  • (ArgumentError) —

    If api_key or api_port is nil, or if sandbox is true but inbox_id is nil, or if incompatible options are provided.



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/mailtrap/client.rb', line 31

def initialize( # rubocop:disable Metrics/ParameterLists
  api_key: ENV.fetch('MAILTRAP_API_KEY'),
  api_host: nil,
  general_api_host: GENERAL_API_HOST,
  api_port: API_PORT,
  bulk: false,
  sandbox: false,
  inbox_id: nil
)
  validate_args!(api_key, api_port, bulk, sandbox, inbox_id)

  api_host ||= select_api_host(bulk:, sandbox:)

  @api_key = api_key
  @api_host = api_host
  @general_api_host = general_api_host
  @api_port = api_port
  @bulk = bulk
  @sandbox = sandbox
  @inbox_id = inbox_id
  @http_clients = {}
end

Instance Attribute Details

#api_host ⇒ Object (readonly)

Returns the value of attribute api_host.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def api_host
  @api_host
end

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def api_key
  @api_key
end

#api_port ⇒ Object (readonly)

Returns the value of attribute api_port.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def api_port
  @api_port
end

#bulk ⇒ Object (readonly)

Returns the value of attribute bulk.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def bulk
  @bulk
end

#general_api_host ⇒ Object (readonly)

Returns the value of attribute general_api_host.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def general_api_host
  @general_api_host
end

#inbox_id ⇒ Object (readonly)

Returns the value of attribute inbox_id.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def inbox_id
  @inbox_id
end

#sandbox ⇒ Object (readonly)

Returns the value of attribute sandbox.



15
16
17
 
# File 'lib/mailtrap/client.rb', line 15

def sandbox
  @sandbox
end

Instance Method Details

#delete(path) ⇒ Hash?

Performs a DELETE request to the specified path

Parameters:

  • path (String) —

    The request path

Returns:

  • (Hash, nil) —

    The JSON response

Raises:



214
215
216
217
218
219
220
 
# File 'lib/mailtrap/client.rb', line 214

def delete(path)
  perform_request(
    method: :delete,
    host: general_api_host,
    path:
  )
end

#get(path, query_params = {}) ⇒ Hash?

Performs a GET request to the specified path

Parameters:

  • path (String) —

    The request path

  • query_params (Hash) (defaults to: {}) —

    Query parameters to append to the URL (optional)

Returns:

  • (Hash, nil) —

    The JSON response

Raises:



173
174
175
176
177
178
179
180
 
# File 'lib/mailtrap/client.rb', line 173

def get(path, query_params = {})
  perform_request(
    method: :get,
    host: general_api_host,
    path:,
    query_params:
  )
end

#patch(path, body = nil) ⇒ Hash?

Performs a PATCH request to the specified path

Parameters:

  • path (String) —

    The request path

  • body (Hash) (defaults to: nil) —

    The request body

Returns:

  • (Hash, nil) —

    The JSON response

Raises:



201
202
203
204
205
206
207
208
 
# File 'lib/mailtrap/client.rb', line 201

def patch(path, body = nil)
  perform_request(
    method: :patch,
    host: general_api_host,
    path:,
    body:
  )
end

#post(path, body = nil) ⇒ Hash?

Performs a POST request to the specified path

Parameters:

  • path (String) —

    The request path

  • body (Hash) (defaults to: nil) —

    The request body

Returns:

  • (Hash, nil) —

    The JSON response

Raises:



187
188
189
190
191
192
193
194
 
# File 'lib/mailtrap/client.rb', line 187

def post(path, body = nil)
  perform_request(
    method: :post,
    host: general_api_host,
    path:,
    body:
  )
end

#send(mail) ⇒ Hash

Sends an email

Examples:

mail = Mailtrap::Mail.from_template(
  from: { email: '[email protected]', name: 'Mailtrap Test' },
  to: [
    { email: '[email protected]' }
  ],
  template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
  template_variables: {
    'user_name' => 'John Doe'
  }
)
client.send(mail)
client.send(
  from: { email: '[email protected]', name: 'Mailtrap Test' },
  to: [
    { email: '[email protected]' }
  ],
  subject: 'You are awesome!',
  text: 'Congrats for sending test email with Mailtrap!'
)

Parameters:

  • mail (#to_json) —

    The email to send

Returns:

  • (Hash) —

    The JSON response

Raises:



159
160
161
162
163
164
165
166
 
# File 'lib/mailtrap/client.rb', line 159

def send(mail)
  perform_request(
    method: :post,
    host: api_host,
    path: send_path,
    body: mail
  )
end

#send_batch(base, requests) ⇒ Hash

Sends a batch of emails.

Examples:

Batch sending with template

batch_base = Mailtrap::Mail.batch_base_from_template(
  from: { email: '[email protected]', name: 'Mailtrap Test' },
  reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
  template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
)

client.send_batch(
  batch_base, [
    Mailtrap::Mail.from_template(
      to: [
        { email: '[email protected]', name: 'John Doe' }
      ],
      template_variables: {
        user_name: 'John Doe'
      }
    ),
    Mailtrap::Mail::Base.new(
      to: [
        { email: '[email protected]', name: 'Jane Doe' }
      ],
      template_variables: {
        user_name: 'Jane Doe'
      }
    ),
    {
      to: [
        { email: '[email protected]', name: 'David Doe' }
      ],
      template_variables: {
        user_name: 'David Doe'
      }
    }
  ]
)

Passing the request parameters directly

client.send_batch(
  {
    from: { email: '[email protected]', name: 'Mailtrap Test' },
    reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
    template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
  }, [
    {
      to: [
        { email: '[email protected]', name: 'John Doe' }
      ],
      template_variables: {
        user_name: 'John Doe'
      }
    },
    {
      to: [
        { email: '[email protected]', name: 'Jane Doe' }
      ],
      template_variables: {
        user_name: 'Jane Doe'
      }
    }
  ]
)

Parameters:

  • base (#to_json) —

    The base email configuration for the batch.

  • requests (Array<#to_json>) —

    Array of individual email requests.

Returns:

  • (Hash) —

    The JSON response from the API.

Raises:



121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/mailtrap/client.rb', line 121

def send_batch(base, requests)
  perform_request(
    method: :post,
    host: api_host,
    path: batch_request_path,
    body: {
      base:,
      requests:
    }
  )
end