Class: Mandrill::Messages

Inherits:

Object

Object
Mandrill::Messages

show all

Defined in:: lib/mandrill/api.rb

Instance Attribute Summary collapse

#master ⇒ Object

Returns the value of attribute master.

Instance Method Summary collapse

#initialize(master) ⇒ Messages constructor

A new instance of Messages.
#parse(raw_message) ⇒ Hash

Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces.
#search(query = '*', date_from = nil, date_to = nil, tags = nil, senders = nil, limit = 100) ⇒ Array

Search the content of recently sent messages and optionally narrow by date range, tags and senders.
#send(message, async = false) ⇒ Array

Send a new transactional message through Mandrill.
#send_raw(raw_message, from_email = nil, from_name = nil, to = nil, async = false) ⇒ Array

Take a raw MIME document for a message, and send it exactly as if it were sent over the SMTP protocol.
#send_template(template_name, template_content, message, async = false) ⇒ Array

Send a new transactional message through Mandrill using a template.

Constructor Details

#initialize(master) ⇒ `Messages`

Returns a new instance of Messages.



427
428
429

# File 'lib/mandrill/api.rb', line 427

def initialize(master)
    @master = master
end

Instance Attribute Details

#master ⇒ `Object`

Returns the value of attribute master.



425
426
427

# File 'lib/mandrill/api.rb', line 425

def master
  @master
end

Instance Method Details

#parse(raw_message) ⇒ `Hash`

Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces

Parameters:

raw_message (String) —

the full MIME document of an email message

Returns:

(Hash) —

the parsed message

String

subject the subject of the message
String

from_email the email address of the sender
String

from_name the alias of the sender (if any)

Array: to an array of any recipients in the message

- [Hash] to[] the information on a single recipient
    - [String] email the email address of the recipient
    - [String] name the alias of the recipient (if any)

Hash

headers the key-value pairs of the MIME headers for the message’s main document
String

text the text part of the message, if any
String

html the HTML part of the message, if any

Array: attachments an array of any attachments that can be found in the message

- [Hash] attachments[] information about an individual attachment
    - [String] name the file name of the attachment
    - [String] type the MIME type of the attachment
    - [Boolean] binary if this is set to true, the attachment is not pure-text, and the content will be base64 encoded
    - [String] content the content of the attachment as a text string or a base64 encoded string based on the attachment type

# File 'lib/mandrill/api.rb', line 586

def parse(raw_message)
    _params = {:raw_message => raw_message}
    return @master.call 'messages/parse', _params
end

#search(query = '*', date_from = nil, date_to = nil, tags = nil, senders = nil, limit = 100) ⇒ `Array`

Search the content of recently sent messages and optionally narrow by date range, tags and senders

Parameters:

query (String) (defaults to: '*') —

the search terms to find matching messages for
date_from (String) (defaults to: nil) —

start date
date_to (String) (defaults to: nil) —

end date
tags (Array) (defaults to: nil) —

an array of tag names to narrow the search to, will return messages that contain ANY of the tags
senders (Array) (defaults to: nil) —

an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
limit (Integer) (defaults to: 100) —

the maximum number of results to return, defaults to 100, 1000 is the maximum

Returns:

(Array) —

of structs for each matching message

Hash: return[] the information for a single matching message

- [Integer] ts the Unix timestamp from when this message was sent
- [String] _id the message's unique id
- [String] sender the email address of the sender
- [String] subject the message's subject link
- [String] email the recipient email address
- [Array] tags list of tags on this message
    - [String] tags[] individual tag on this message
- [Integer] opens how many times has this message been opened
- [Integer] clicks how many times has a link been clicked in this message
- [String] state sending status of this message: sent, bounced, rejected
- [Hash] metadata any custom metadata provided when the message was sent

# File 'lib/mandrill/api.rb', line 562

def search(query='*', date_from=nil, date_to=nil, tags=nil, senders=nil, limit=100)
    _params = {:query => query, :date_from => date_from, :date_to => date_to, :tags => tags, :senders => senders, :limit => limit}
    return @master.call 'messages/search', _params
end

#send(message, async = false) ⇒ `Array`

Send a new transactional message through Mandrill

Parameters:

message (Hash) —
the information on the message to send
- String
  
  html the full HTML content to be sent
- String
  
  text optional full text content to be sent
- String
  
  subject the message subject
- String
  
  from_email the sender email address.
- String
  
  from_name optional from name to be used
- Array
  
  to an array of recipient information.
```
- [Hash] to[] a single recipient's information.
    - [String] email the email address of the recipient
    - [String] name the optional display name to use for the recipient
```
- Hash
  
  headers optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed)
- Boolean
  
  track_opens whether or not to turn on open tracking for the message
- Boolean
  
  track_clicks whether or not to turn on click tracking for the message
- Boolean
  
  auto_text whether or not to automatically generate a text part for messages that are not given text
- Boolean
  
  url_strip_qs whether or not to strip the query string from URLs when aggregating tracked URL data
- Boolean
  
  preserve_recipients whether or not to expose all recipients in to “To” header for each email
- String
  
  bcc_address an optional address to receive an exact copy of each recipient’s email
- Boolean
  
  merge whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided.
- Array
  
  global_merge_vars global merge variables to use for all recipients. You can override these per recipient.
```
- [Hash] global_merge_vars[] a single global merge variable
    - [String] name the global merge variable's name. Merge variable names are case-insensitive and may not start with _
    - [String] content the global merge variable's content
```
- Array
  
  merge_vars per-recipient merge variables, which override global merge variables with the same name.
```
- [Hash] merge_vars[] per-recipient merge variables
    - [String] rcpt the email address of the recipient that the merge variables should apply to
    - [Array] vars the recipient's merge variables
        - [Hash] vars[] a single merge variable
            - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
            - [String] content the merge variable's content
```
- Array
  
  tags an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
```
- [String] tags[] a single tag - must not start with an underscore
```
- Array
  
  google_analytics_domains an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.
- Array, String
  
  google_analytics_campaign optional string indicating the value to set for the utm_campaign tracking parameter. If this isn’t provided the email’s from address will be used instead.
- Array
  
  metadata metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.
- Array
  
  recipient_metadata Per-recipient metadata that will override the global values specified in the metadata parameter.
```
- [Hash] recipient_metadata[] metadata for a single recipient
    - [String] rcpt the email address of the recipient that the metadata is associated with
    - [Array] values an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.
```
- Array
  
  attachments an array of supported attachments to add to the message
```
- [Hash] attachments[] a single supported attachment
    - [String] type the MIME type of the attachment - allowed types are text/*, image/*, and application/pdf
    - [String] name the file name of the attachment
    - [String] content the content of the attachment as a base64-encoded string
```
async (Boolean) (defaults to: false) —

enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of “queued” for every recipient. To handle rejections when sending in async mode, set up a webhook for the ‘reject’ event. Defaults to false for messages with fewer than 100 recipients; messages with more than 100 recipients are always sent asynchronously, regardless of the value of async.

Returns:

(Array) —
of structs for each recipient containing the key “email” with the email address and “status” as either “sent”, “queued”, or “rejected”
- Hash
  
  return[] the sending results for a single recipient
```
- [String] email the email address of the recipient
- [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
```

# File 'lib/mandrill/api.rb', line 480

def send(message, async=false)
    _params = {:message => message, :async => async}
    return @master.call 'messages/send', _params
end

#send_raw(raw_message, from_email = nil, from_name = nil, to = nil, async = false) ⇒ `Array`

Take a raw MIME document for a message, and send it exactly as if it were sent over the SMTP protocol

Parameters:

raw_message (String) —

the full MIME document of an email message
from_email (String, nil) (defaults to: nil) —

optionally define the sender address - otherwise we’ll use the address found in the provided headers
from_name (String, nil) (defaults to: nil) —

optionally define the sender alias
to (Array, nil) (defaults to: nil) —
optionally define the recipients to receive the message - otherwise we’ll use the To, Cc, and Bcc headers provided in the document
- String
  
  to[] the email address of the recipint
async (Boolean) (defaults to: false) —

enable a background sending mode that is optimized for bulk sending. In async mode, messages/sendRaw will immediately return a status of “queued” for every recipient. To handle rejections when sending in async mode, set up a webhook for the ‘reject’ event. Defaults to false for messages with fewer than 100 recipients; messages with more than 100 recipients are always sent asynchronously, regardless of the value of async.

Returns:

(Array) —
of structs for each recipient containing the key “email” with the email address and “status” as either “sent”, “queued”, or “rejected”
- Hash
  
  return[] the sending results for a single recipient
```
- [String] email the email address of the recipient
- [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
```

# File 'lib/mandrill/api.rb', line 602

def send_raw(raw_message, from_email=nil, from_name=nil, to=nil, async=false)
    _params = {:raw_message => raw_message, :from_email => from_email, :from_name => from_name, :to => to, :async => async}
    return @master.call 'messages/send-raw', _params
end

#send_template(template_name, template_content, message, async = false) ⇒ `Array`

Send a new transactional message through Mandrill using a template

Parameters:

template_name (String) —

the name of a template that exists in the user’s account
template_content (Array) —
an array of template content to send. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block
- Hash
  
  template_content[] the injection of a single piece of content into a single editable region
```
- [String] name the name of the mc:edit editable region to inject into
- [String] content the content to inject
```
message (Hash) —
the other information on the message to send - same as /messages/send, but without the html content
- String
  
  text optional full text content to be sent
- String
  
  subject the message subject
- String
  
  from_email the sender email address.
- String
  
  from_name optional from name to be used
- Array
  
  to an array of recipient information.
```
- [Hash] to[] a single recipient's information.
    - [String] email the email address of the recipient
    - [String] name the optional display name to use for the recipient
```
- Hash
  
  headers optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed)
- Boolean
  
  track_opens whether or not to turn on open tracking for the message
- Boolean
  
  track_clicks whether or not to turn on click tracking for the message
- Boolean
  
  auto_text whether or not to automatically generate a text part for messages that are not given text
- Boolean
  
  url_strip_qs whether or not to strip the query string from URLs when aggregating tracked URL data
- Boolean
  
  preserve_recipients whether or not to expose all recipients in to “To” header for each email
- String
  
  bcc_address an optional address to receive an exact copy of each recipient’s email
- Array
  
  global_merge_vars global merge variables to use for all recipients. You can override these per recipient.
```
- [Hash] global_merge_vars[] a single global merge variable
    - [String] name the global merge variable's name. Merge variable names are case-insensitive and may not start with _
    - [String] content the global merge variable's content
```
- Array
  
  merge_vars per-recipient merge variables, which override global merge variables with the same name.
```
- [Hash] merge_vars[] per-recipient merge variables
    - [String] rcpt the email address of the recipient that the merge variables should apply to
    - [Array] vars the recipient's merge variables
        - [Hash] vars[] a single merge variable
            - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
            - [String] content the merge variable's content
```
- Array
  
  tags an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
```
- [String] tags[] a single tag - must not start with an underscore
```
- Array
  
  google_analytics_domains an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.
- Array, String
  
  google_analytics_campaign optional string indicating the value to set for the utm_campaign tracking parameter. If this isn’t provided the email’s from address will be used instead.
- Array
  
  metadata metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.
- Array
  
  recipient_metadata Per-recipient metadata that will override the global values specified in the metadata parameter.
```
- [Hash] recipient_metadata[] metadata for a single recipient
    - [String] rcpt the email address of the recipient that the metadata is associated with
    - [Array] values an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.
```
- Array
  
  attachments an array of supported attachments to add to the message
```
- [Hash] attachments[] a single supported attachment
    - [String] type the MIME type of the attachment - allowed types are text/*, image/*, and application/pdf
    - [String] name the file name of the attachment
    - [String] content the content of the attachment as a base64-encoded string
```
async (Boolean) (defaults to: false) —

enable a background sending mode that is optimized for bulk sending. In async mode, messages/sendTemplate will immediately return a status of “queued” for every recipient. To handle rejections when sending in async mode, set up a webhook for the ‘reject’ event. Defaults to false for messages with fewer than 100 recipients; messages with more than 100 recipients are always sent asynchronously, regardless of the value of async.

Returns:

(Array) —
of structs for each recipient containing the key “email” with the email address and “status” as either “sent”, “queued”, or “rejected”
- Hash
  
  return[] the sending results for a single recipient
```
- [String] email the email address of the recipient
- [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
```

# File 'lib/mandrill/api.rb', line 537

def send_template(template_name, template_content, message, async=false)
    _params = {:template_name => template_name, :template_content => template_content, :message => message, :async => async}
    return @master.call 'messages/send-template', _params
end

Class: Mandrill::Messages

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(master) ⇒ Messages

Instance Attribute Details

#master ⇒ Object

Instance Method Details

#parse(raw_message) ⇒ Hash

#search(query = '*', date_from = nil, date_to = nil, tags = nil, senders = nil, limit = 100) ⇒ Array

#send(message, async = false) ⇒ Array

#send_raw(raw_message, from_email = nil, from_name = nil, to = nil, async = false) ⇒ Array

#send_template(template_name, template_content, message, async = false) ⇒ Array

#initialize(master) ⇒ `Messages`

#master ⇒ `Object`

#parse(raw_message) ⇒ `Hash`

#search(query = '*', date_from = nil, date_to = nil, tags = nil, senders = nil, limit = 100) ⇒ `Array`

#send(message, async = false) ⇒ `Array`

#send_raw(raw_message, from_email = nil, from_name = nil, to = nil, async = false) ⇒ `Array`

#send_template(template_name, template_content, message, async = false) ⇒ `Array`