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:

  • (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.

  • (defaults to: nil)

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

  • (defaults to: GENERAL_API_HOST)

    The Mailtrap general API hostname for non-sending operations.

  • (defaults to: API_PORT)

    The Mailtrap API port. Default: 443.

  • (defaults to: false)

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

  • (defaults to: false)

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

  • (defaults to: nil)

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

Raises:

  • 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:

  • The request path

Returns:

  • JSON response or raw response body

Raises:

  • If the API request fails with a client or server error

  • If the API key is invalid

  • If the server refuses to process the request

  • If too many requests are made



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:

  • The request path

  • (defaults to: {})

    Query parameters to append to the URL (optional)

Returns:

  • JSON response or raw response body

Raises:

  • If the API request fails with a client or server error

  • If the API key is invalid

  • If the server refuses to process the request

  • If too many requests are made



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:

  • The request path

  • (defaults to: nil)

    The request body

Returns:

  • JSON response or raw response body

Raises:

  • If the API request fails with a client or server error

  • If the API key is invalid

  • If the server refuses to process the request

  • If too many requests are made



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:

  • The request path

  • (defaults to: nil)

    The request body

Returns:

  • JSON response or raw response body

Raises:

  • If the API request fails with a client or server error

  • If the API key is invalid

  • If the server refuses to process the request

  • If too many requests are made



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:

  • The email to send

Returns:

  • JSON response or raw response body

Raises:

  • If the API request fails with a client or server error

  • If the API key is invalid

  • If the server refuses to process the request

  • If too many requests are made

  • If the message is too large



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:

  • The base email configuration for the batch.

  • Array of individual email requests.

Returns:

  • JSON response or raw response body from the API.

Raises:

  • If the API request fails with a client or server error

  • If the API key is invalid

  • If the server refuses to process the request

  • If too many requests are made

  • If the message is too large.



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