class ExpressPigeon::Lists

Lists

Lists are sets of contacts a campaign can be sent to. A list consists of name, from name, reply-to fields and physical address that will be displayed in newsletter. Lists can be created, read, updated, deleted and filled up with contacts.

Note: each list has properties, including physical address. Such address is merged into footers of newsletters when campaigns are sent to a list. It allows to send to different lists of contacts and display different physical addresses at the bottom of newsletters depending which list such email was sent to. This is a useful feature for agencies who manage email marketing campaigns on behalf of their clients.

Public Class Methods

new(auth_key) click to toggle source
# File lib/express_pigeon/lists.rb, line 21
def initialize(auth_key)
  self.class.headers('X-auth-key' => auth_key)
end

Public Instance Methods

create(name:, from_name:, reply_to:) click to toggle source

Create a new list POST api.expresspigeon.com/lists

name: Name of a newly created list from_name: Default “from” name used when sending campaigns to this list reply_to: Default reply To email address used when sending campaigns to this list

# File lib/express_pigeon/lists.rb, line 31
def create(name:, from_name:, reply_to:)
  options = {
    'name' => name,
    'from_name' => from_name,
    'reply_to' => reply_to
  }

  self.class.post(
    '/',
    body: options.to_json,
    headers: { 'Content-Type' => 'application/json' }
  )
end
delete(list_id) click to toggle source

Delete a list DELETE api.expresspigeon.com/lists/{list_id}

# File lib/express_pigeon/lists.rb, line 77
def delete(list_id)
  self.class.delete("/#{list_id}")
end
download_csv(list_id, download_path) click to toggle source

Download contacts from list GET api.expresspigeon.com/lists/{list_id}/csv

# File lib/express_pigeon/lists.rb, line 83
def download_csv(list_id, download_path)
  fail "File found at '#{download_path}' but will not overwrite." if File.exist?(download_path)

  response = self.class.get("/#{list_id}/csv")

  File.open(download_path, 'a+') do |f|
    f.write response.body
  end

  response
end
find_by_name(name) click to toggle source
# File lib/express_pigeon/lists.rb, line 57
def find_by_name(name)
  index.select do |list|
    list['name'] == name
  end
end
index() click to toggle source

Get all lists GET api.expresspigeon.com/lists

# File lib/express_pigeon/lists.rb, line 53
def index
  self.class.get('/')
end
update(list_id, name: nil, from_name: nil, reply_to: nil) click to toggle source

Update existing list PUT api.expresspigeon.com/lists

# File lib/express_pigeon/lists.rb, line 97
def update(list_id, name: nil, from_name: nil, reply_to: nil)
  options = {}
  options['name'] = name unless name.nil?
  options['from_name'] = from_name unless from_name.nil?
  options['reply_to'] = reply_to unless reply_to.nil?

  # if we didn't provide any options then it's a NOOP
  return nil if options.empty?

  options['id'] = list_id

  self.class.put(
    '/',
    body: options.to_json,
    headers: {
      'Content-Type' => 'application/json'
    }
  )
end
upload(list_id, path) click to toggle source

Upload contacts to list POST api.expresspigeon.com/lists/{list_id}/upload

# File lib/express_pigeon/lists.rb, line 65
def upload(list_id, path)
  fail "No file found at '#{path}'." unless File.exist?(path)

  self.class.post(
    "/#{list_id}/upload",
    query: { contacts_file: File.new(path, 'r') },
    detect_mime_type: true
  )
end
upload_status(upload_id) click to toggle source

Check the status of list upload GET api.expresspigeon.com/lists/upload_status/{upload_id}

# File lib/express_pigeon/lists.rb, line 47
def upload_status(upload_id)
  self.class.get("/upload_status/#{upload_id}")
end