Method: Mandrill::Messages#search

Defined in:

lib/mandrill/api.rb

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

Search recently sent messages and optionally narrow by date range, tags, senders, and API keys. If no date range is specified, results within the last 7 days are returned. This method may be called up to 20 times per minute. If you need the data more often, you can use <a href=“/api/docs/messages.html#method=info”>/messages/info.json</a> to get the information for a single message, or <a href=“help.mandrill.com/entries/21738186-Introduction-to-Webhooks”>webhooks</a> to push activity to your own application for querying.

Parameters:

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

  <a href=“help.mandrill.com/entries/22211902”>search terms</a> to find matching messages

• 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

• api_keys (Array) (defaults to: nil) —

  an array of API keys to narrow the search to, will return messages sent by ANY of the keys

• 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] template the unique name of the template used, if any
    - [String] subject the message's subject line
    - [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
    - [Array] opens_detail list of individual opens for the message
        - [Hash] opens_detail[] information on an individual open
            - [Integer] ts the unix timestamp from when the message was opened
            - [String] ip the IP address that generated the open
            - [String] location the approximate region and country that the opening IP is located
            - [String] ua the email client or browser data of the open
    - [Integer] clicks how many times has a link been clicked in this message
    - [Array] clicks_detail list of individual clicks for the message
        - [Hash] clicks_detail[] information on an individual click
            - [Integer] ts the unix timestamp from when the message was clicked
            - [String] url the URL that was clicked on
            - [String] ip the IP address that generated the click
            - [String] location the approximate region and country that the clicking IP is located
            - [String] ua the email client or browser data of the click
    - [String] state sending status of this message: sent, bounced, rejected
    - [Hash] metadata any custom metadata provided when the message was sent
    

  • Array

    smtp_events a log of up to 3 smtp events for the message

    - [Hash] smtp_events[] information about a specific smtp event
        - [Integer] ts the Unix timestamp when the event occured
        - [String] type the message's state as a result of this event
        - [String] diag the SMTP response from the recipient's server
    

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

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