Class: Mailosaur::Messages

Inherits:
Object
  • Object
show all
Defined in:
lib/Mailosaur/messages.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(conn, handle_http_error) ⇒ Messages

Creates and initializes a new instance of the Messages class.

Parameters:

  • client —

    connection.



9
10
11
12
 
# File 'lib/Mailosaur/messages.rb', line 9

def initialize(conn, handle_http_error)
  @conn = conn
  @handle_http_error = handle_http_error
end

Instance Attribute Details

#conn ⇒ Connection (readonly)

Returns the client connection.

Returns:

  • (Connection) —

    the client connection.



15
16
17
 
# File 'lib/Mailosaur/messages.rb', line 15

def conn
  @conn
end

Instance Method Details

#create(server, message_create_options) ⇒ Message

Create a message.

Creates a new message that can be sent to a verified email address. This is useful in scenarios where you want an email to trigger a workflow in your product

Parameters:

  • server (String) —

    The identifier of the server to create the message in.

  • options (MessageCreateOptions) —

    The options with which to create the message.

Returns:

  • (Message) —

    operation result.



196
197
198
199
200
201
 
# File 'lib/Mailosaur/messages.rb', line 196

def create(server, message_create_options)
  response = conn.post "api/messages?server=#{server}", message_create_options.to_json
  @handle_http_error.call(response) unless response.status == 200
  model = JSON.parse(response.body)
  Mailosaur::Models::Message.new(model)
end

#delete(id) ⇒ Object

Delete a message

Permanently deletes a message. This operation cannot be undone. Also deletes any attachments related to the message.

Parameters:

  • id —

    The identifier of the message to be deleted.



68
69
70
71
72
 
# File 'lib/Mailosaur/messages.rb', line 68

def delete(id)
  response = conn.delete "api/messages/#{id}"
  @handle_http_error.call(response) unless response.status == 204
  nil
end

#delete_all(server) ⇒ Object

Delete all messages

Permanently deletes all messages held by the specified server. This operation cannot be undone. Also deletes any attachments related to each message.

Parameters:

  • server (String) —

    The identifier of the server to be emptied.



116
117
118
119
120
 
# File 'lib/Mailosaur/messages.rb', line 116

def delete_all(server)
  response = conn.delete "api/messages?server=#{server}"
  @handle_http_error.call(response) unless response.status == 204
  nil
end

#forward(id, message_forward_options) ⇒ Message

Forward an email.

Forwards the specified email to a verified email address.

against.

Parameters:

  • id (String) —

    The identifier of the email to forward.

  • options (MessageForwardOptions) —

    The options with which to forward the email.

Returns:

  • (Message) —

    operation result.



214
215
216
217
218
219
 
# File 'lib/Mailosaur/messages.rb', line 214

def forward(id, message_forward_options)
  response = conn.post "api/messages/#{id}/forward", message_forward_options.to_json
  @handle_http_error.call(response) unless response.status == 200
  model = JSON.parse(response.body)
  Mailosaur::Models::Message.new(model)
end

#generate_previews(id, options) ⇒ PreviewListResult

Generate email previews.

Generates screenshots of an email rendered in the specified email clients.

Parameters:

  • id (String) —

    The identifier of the email to preview.

  • options (PreviewRequestOptions) —

    The options with which to generate previews.

Returns:

  • (PreviewListResult) —

    operation result.



250
251
252
253
254
255
 
# File 'lib/Mailosaur/messages.rb', line 250

def generate_previews(id, options)
  response = conn.post "api/messages/#{id}/previews", options.to_json
  @handle_http_error.call(response) unless response.status == 200
  model = JSON.parse(response.body)
  Mailosaur::Models::PreviewListResult.new(model)
end

#get(server, criteria, timeout: 10_000, received_after: DateTime.now - (1.0 / 24), dir: nil) ⇒ Message

Retrieve a message using search criteria

Returns as soon as a message matching the specified search criteria is found. This is the most efficient method of looking up a message.

a match. (in milliseconds). after this date/time. or ‘Received`), with the default being `Received`.

Parameters:

  • server (String) —

    The identifier of the server hosting the message.

  • criteria (SearchCriteria) —

    The search criteria to use in order to find

  • timeout (Integer) (defaults to: 10_000) —

    Specify how long to wait for a matching result

  • received_after (DateTime) (defaults to: DateTime.now - (1.0 / 24)) —

    Limits results to only messages received

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

    Optionally limits results based on the direction (‘Sent`

Returns:

  • (Message) —

    operation results.

Raises:



35
36
37
38
39
40
41
 
# File 'lib/Mailosaur/messages.rb', line 35

def get(server, criteria, timeout: 10_000, received_after: DateTime.now - (1.0 / 24), dir: nil)
  # Defaults timeout to 10s, receivedAfter to 1h
  raise Mailosaur::MailosaurError.new('Must provide a valid Server ID.', 'invalid_request') if server.length != 8

  result = search(server, criteria, page: 0, items_per_page: 1, timeout: timeout, received_after: received_after, dir: dir)
  get_by_id(result.items[0].id)
end

#get_by_id(id) ⇒ Message

Retrieve a message

Retrieves the detail for a single email message. Simply supply the unique identifier for the required message.

Parameters:

  • id —

    The identifier of the email message to be retrieved.

Returns:

  • (Message) —

    operation results.



53
54
55
56
57
58
 
# File 'lib/Mailosaur/messages.rb', line 53

def get_by_id(id)
  response = conn.get "api/messages/#{id}"
  @handle_http_error.call(response) unless response.status == 200
  model = JSON.parse(response.body)
  Mailosaur::Models::Message.new(model)
end

#list(server, page: nil, items_per_page: nil, received_after: nil, dir: nil) ⇒ MessageListResult

List all messages

Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.

pagination. returned per page. Can be set between 1 and 1000 items, the default is 50. after this date/time. or ‘Received`), with the default being `Received`.

Parameters:

  • server (String) —

    The identifier of the server hosting the messages.

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

    Used in conjunction with ‘itemsPerPage` to support

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

    A limit on the number of results to be

  • received_after (DateTime) (defaults to: nil) —

    Limits results to only messages received

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

    Optionally limits results based on the direction (‘Sent`

Returns:

  • (MessageListResult) —

    operation results.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/Mailosaur/messages.rb', line 93

def list(server, page: nil, items_per_page: nil, received_after: nil, dir: nil)
  url = "api/messages?server=#{server}"
  url += page ? "&page=#{page}" : ''
  url += items_per_page ? "&itemsPerPage=#{items_per_page}" : ''
  url += received_after ? "&receivedAfter=#{CGI.escape(received_after.iso8601)}" : ''
  url += dir ? "&dir=#{dir}" : ''

  response = conn.get url

  @handle_http_error.call(response) unless response.status == 200

  model = JSON.parse(response.body)
  Mailosaur::Models::MessageListResult.new(model)
end

#reply(id, message_reply_options) ⇒ Message

Reply to an email.

Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.

against.

Parameters:

  • id (String) —

    The identifier of the email to reply to.

  • options (MessageReplyOptions) —

    The options with which to reply to the email.

Returns:

  • (Message) —

    operation result.



233
234
235
236
237
238
 
# File 'lib/Mailosaur/messages.rb', line 233

def reply(id, message_reply_options)
  response = conn.post "api/messages/#{id}/reply", message_reply_options.to_json
  @handle_http_error.call(response) unless response.status == 200
  model = JSON.parse(response.body)
  Mailosaur::Models::Message.new(model)
end

#search(server, criteria, page: nil, items_per_page: nil, timeout: nil, received_after: nil, error_on_timeout: true, dir: nil) ⇒ MessageListResult

Search for messages

Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

against. pagination. returned per page. Can be set between 1 and 1000 items, the default is 50. (in milliseconds). after this date/time. throw if timeout is reached (default: true). or ‘Received`), with the default being `Received`.

Parameters:

  • server (String) —

    The identifier of the server hosting the messages.

  • criteria (SearchCriteria) —

    The search criteria to match results

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

    Used in conjunction with ‘itemsPerPage` to support

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

    A limit on the number of results to be

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

    Specify how long to wait for a matching result

  • received_after (DateTime) (defaults to: nil) —

    Limits results to only messages received

  • error_on_timeout (Boolean) (defaults to: true) —

    When set to false, an error will not be

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

    Optionally limits results based on the direction (‘Sent`

Returns:

  • (MessageListResult) —

    operation results.



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/Mailosaur/messages.rb', line 147

def search(server, criteria, page: nil, items_per_page: nil, timeout: nil, received_after: nil, error_on_timeout: true, dir: nil)
  url = "api/messages/search?server=#{server}"
  url += page ? "&page=#{page}" : ''
  url += items_per_page ? "&itemsPerPage=#{items_per_page}" : ''
  url += received_after ? "&receivedAfter=#{CGI.escape(received_after.iso8601)}" : ''
  url += dir ? "&dir=#{dir}" : ''

  poll_count = 0
  start_time = Time.now.to_f

  loop do
    response = conn.post url, criteria.to_json

    @handle_http_error.call(response) unless response.status == 200

    model = JSON.parse(response.body)
    return Mailosaur::Models::MessageListResult.new(model) if timeout.to_i.zero? || !model['items'].empty?

    delay_pattern = (response.headers['x-ms-delay'] || '1000').split(',').map(&:to_i)

    delay = poll_count >= delay_pattern.length ? delay_pattern[delay_pattern.length - 1] : delay_pattern[poll_count]

    poll_count += 1

    ## Stop if timeout will be exceeded
    if ((1000 * (Time.now.to_f - start_time).to_i) + delay) > timeout
      return Mailosaur::Models::MessageListResult.new(model) unless error_on_timeout

      msg = format('No matching messages found in time. By default, only messages received in the last hour are checked (use receivedAfter to override this). The search criteria used for this query was [%s] which timed out after %sms',
                   criteria.to_json, timeout)
      raise Mailosaur::MailosaurError.new(msg, 'search_timeout')
    end

    sleep(delay / 1000)
  end
end