Class: Litmus::Instant

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/litmus/instant.rb,
lib/litmus/instant/version.rb

Defined Under Namespace

Classes: ApiError, AuthenticationError, AuthorizationError, Client, Error, InactiveUserError, InvalidOAuthScope, InvalidOAuthToken, NetworkError, NotFound, RequestError, ServiceError, TimeoutError

Constant Summary collapse

VERSION = 
"0.3.1"

Class Method Summary collapse

Class Method Details

.api_key(key = nil) ⇒ String

Get or set your Instant API key

Returns:

  • (String) 


73
74
75
76
 
# File 'lib/litmus/instant.rb', line 73

def self.api_key(key = nil)
  self.api_key = key if key
  @key
end

.api_key=(key) ⇒ Object

Set your Instant API key



79
80
81
82
83
 
# File 'lib/litmus/instant.rb', line 79

def self.api_key=(key)
  self.default_options.delete :basic_auth
  basic_auth key, "" if key
  @key = key
end

.client_configurations ⇒ Hash

List supported email client configurations

Returns:

  • (Hash) —

    hash keyed by email client name, values are a Hash with the the keys orientation_options and images_options



160
161
162
 
# File 'lib/litmus/instant.rb', line 160

def self.client_configurations
  get "/clients/configurations"
end

.clients ⇒ Array<String>

List supported email clients

Returns:

  • (Array<String>) —

    array of email client names



153
154
155
 
# File 'lib/litmus/instant.rb', line 153

def self.clients
  get "/clients"
end

.create_email(email) ⇒ Hash

Describe an email’s content and metadata and, in exchange, receive an email_guid required to capture previews of it

We intend these objects to be treated as lightweight. Once uploaded, emails can’t be modified. Obtain a new email_guid each time changes need to be reflected.

The uploaded email has a limited lifespan. As a result, a new email_guid should be obtained before requesting new previews if more than a day has passed since the last upload.

At least one of :html_text, :plain_text, :raw_source must be provided.

Parameters:

  • email (Hash)
  • token (String) —

    optional OAuth authentication token when calling on behalf of a Litmus user. This will be different for each OAuth connected user.

Options Hash (email):

  • :html_text (String)
  • :plain_text (String)
  • :subject (String)
  • :from_address (String)
  • :from_display_name (String)
  • :raw_source (String) —

    This field provides an alternative approach to defining the email and so is only valid in the absence of all the fields above

  • :end_user_id (String) —

    A unique identifier for your end users. When provided, we use this to partition your usage data. See litmus.com/partners/api/documentation/instant/03-identifying-end-users/

  • :configurations (Array<Hash>) —

    An array of capture capture configuration hashes This allows pre-requesting previews that should be captured as soon as possible. This can be a useful performance optimisation. See .prefetch_previews for further detail on format.

Returns:

  • (Hash) —

    the response containing the email_guid and also confirmation of end_user_id and configurations if provided



147
148
149
 
# File 'lib/litmus/instant.rb', line 147

def self.create_email(email)
  post("/emails", body: email.to_json)
end

.get_preview(email_guid, client, options = {}) ⇒ Hash

Request a preview

This triggers the capture of a preview. The method blocks until capture completes. The response contains URLs for each of the image sizes available. A further request will be needed to obtain actual image data from one of the provided URLs.

Parameters:

  • email_guid (String)
  • client (String)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :images (String) —

    allowed (default) or blocked

  • :orientation (String) —

    horizontal or vertical (default)

Returns:

  • (Hash) —

    a hash mapping the available capture sizes to their corresponding URLs



179
180
181
182
 
# File 'lib/litmus/instant.rb', line 179

def self.get_preview(email_guid, client, options = {})
  query = URI.encode_www_form(options)
  get "/emails/#{email_guid}/previews/#{client}?#{query}"
end

.oauth_token(token = nil) ⇒ String

Get or set a global OAuth token to use This is not thread safe, if you intend to authorize multiple end users within the same application use

Litmus::Instant::Client.new(oauth_token: "XXX")

Returns:

  • (String) 


92
93
94
95
 
# File 'lib/litmus/instant.rb', line 92

def self.oauth_token(token = nil)
  self.api_token = token if token
  @token
end

.oauth_token=(token) ⇒ Object

Set an OAuth token to be used globally This is not thread safe, if you intend to authorize multiple end users within the same application use

Litmus::Instant::Client.new(oauth_token: "XXX")



103
104
105
106
107
 
# File 'lib/litmus/instant.rb', line 103

def self.oauth_token=(token)
  self.default_options[:headers].delete "Authorization"
  self.headers("Authorization" => "Bearer #{token}") if token
  @token = token
end

.prefetch_previews(email_guid, configurations) ⇒ Hash

Pre-request a set of previews before download

This method is provided as an optional performance enhancement, typically useful before embedding a set of previews within a browser, where connection limits might otherwise delay the start of capture of some previews.

The method does not block while capture occurs, a response is returned immediately.

Note that should capture failure occur for a preview, it will only be discovered when the preview is later requested. Request errors, for instance attempting to prefetch an invalid client, will result raise normally howver.

Parameters:

  • email_guid (String)
  • configurations (Array<Hash>) —

    An array of capture capture configurations Each configuration Hash must have a :client key, and optional :orientation and images keys

Returns:

  • (Hash) —

    confirmation of the configurations being captured



205
206
207
 
# File 'lib/litmus/instant.rb', line 205

def self.prefetch_previews(email_guid, configurations)
  post "/emails/#{email_guid}/previews/prefetch", body: { configurations: configurations }.to_json
end

.preview_image_url(email_guid, client, options = {}) ⇒ String

Construct a preview image URL ready for download

The generated URLs can be embedded directly within a client application, for instance with the src tag of an HTML img tag.

This is also useful for downloading a capture in a single step, rather than calling .get_preview then making a follow up request to retrieve the image data.

Parameters:

  • email_guid (String)
  • client (String)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :capture_size (String) —

    full (default), thumb or thumb450

  • :images (String) —

    allowed (default) or blocked

  • :orientation (String) —

    horizontal or vertical (default)

  • :fallback (Boolean) —

    by default errors during capture redirect to a fallback image, setting this to false will mean that GETs to the resulting URL will receive HTTP error responses instead

  • :fallback_url (String) —

    a custom fallback image to display in case of errors. This must be an absolute URL and have a recognizable image extension. Query parameters are not supported. The image should be accessible publicly without the need for authentication.

Returns:

  • (String) —

    the preview URL, domain sharded by the client name



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/litmus/instant.rb', line 233

def self.preview_image_url(email_guid, client, options = {})
  # We'd use Ruby 2.x keyword args here, but it's more useful to preserve
  # compatibility for anyone stuck with ruby < 2.x
  capture_size = options.delete(:capture_size) || "full"

  if options.keys.length > 0
    if options[:fallback_url]
      options[:fallback_url] = CGI.escape(options[:fallback_url])
    end
    query = URI.encode_www_form(options)
    "#{sharded_base_uri(client)}/emails/#{email_guid}/previews/#{client}/#{capture_size}?#{query}"
  else
    "#{sharded_base_uri(client)}/emails/#{email_guid}/previews/#{client}/#{capture_size}"
  end
end