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.0"

Class Method Summary collapse

Class Method Details

.api_key(key = nil) ⇒ String

Get or set your Instant API key


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_configurationsHash

List supported email client configurations


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

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

.clientsArray<String>

List supported email clients


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.

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.


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.

Options Hash (options):

  • :images (String)

    allowed (default) or blocked

  • :orientation (String)

    horizontal or vertical (default)


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")

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.


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.

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.


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