class Emarsys::Contact

Methods for the Contact API

Public Class Methods

batch_params(params = []) click to toggle source

@private

# File lib/emarsys/data_objects/contact.rb, line 174
def batch_params(params = [])
  params.map { |p| Emarsys::ParamsConverter.new(p).convert_to_ids }
end
contact_history(contacts:, account: nil) click to toggle source

Get list of emails send to a contact

@param contacts [array] Array of contact ids @return [Hash] result data @example

Emarsys::Contact.contact_history(contacts: [1,2,3]
# File lib/emarsys/data_objects/contact.rb, line 109
def contact_history(contacts:, account: nil)
  post account, "contact/getcontacthistory", {'contacts' => contacts}
end
create(key_id:, key_value:, params: {}, account: nil) click to toggle source

Create a new contact. The given params are transformed to emarsys ids.

@param key_id [Integer, String] internal id of key field @param key_value [Integer, String] value of internal id field @param params [Hash] Contact information to create @return [Hash] internal id of the contact @example

Emarsys::Contact.create(key_id: 'app_id', key_value: 23, params: {:firstname => "Jon", :lastname => "Doe"})
Emarsys::Contact.create(key_id: '3', key_value: 'john.doe@example.com', params:  {'1' => "Jon", '2' => "Doe"})
# File lib/emarsys/data_objects/contact.rb, line 19
def create(key_id:, key_value:, params: {}, account: nil)
  transformed_key_id = transform_key_id(key_id)
  post account, "contact", params.merge!({'key_id' => transformed_key_id, transformed_key_id => key_value})
end
create_batch(key_id:, params: [], account: nil) click to toggle source

Batch creation of contacts.

@param key_id [Integer, String] internal id of key field @param params [Hash] Contact information of each new contact @example

Emarsys::Contact.create_batch(
  key_id: 'email',
  params: [
    {:app_id => 1, :firstname => "Jon", :lastname => "Doe"},
    {:app_id => 2, :firstname => "Jane", :lastname => "Doe"}
  ]
)
# File lib/emarsys/data_objects/contact.rb, line 65
def create_batch(key_id:, params: [], account: nil)
  post account, "contact", {'key_id' => transform_key_id(key_id), 'contacts' => batch_params(params)}
end
delete(key_id:, key_value:, account: nil) click to toggle source

Delete a contact. The given params are transformed to emarsys ids.

@param key_id [Integer, String] internal id of key field @param key_value [Integer, String] value of internal id field @return [Hash] @example

Emarsys::Contact.delete(key_id: 'app_id', key_value: 23)
Emarsys::Contact.delete(key_id: '3', key_value: 'john.doe@example.com')
# File lib/emarsys/data_objects/contact.rb, line 97
def delete(key_id:, key_value:, account: nil)
  path = "contact/delete"
  transformed_key_id = transform_key_id(key_id)
  post account, path, {'key_id' => transformed_key_id, transformed_key_id => key_value}
end
emarsys_id(key_id:, key_value:, account: nil) click to toggle source

Get the internal emarsys id of a contact. The given params are transformed to emarsys ids.

@param key_id [Integer, String] internal id of key field @param key_value [Integer, String] value of internal id field @return [Hash] internal emarsys id of the contact @example

Emarsys::Contact.emarsys_id(key_id: 'email', key_value: 'john.dow@example.com')
Emarsys::Contact.emarsys_id(key_id: 1, key_value: 'John')
# File lib/emarsys/data_objects/contact.rb, line 32
def emarsys_id(key_id:, key_value:, account: nil)
  get account, "contact", {"#{transform_key_id(key_id).to_s}" => key_value}
end
export_registrations(distribution_method:, time_range:, contact_fields:, account: nil, **params) click to toggle source

Exports the selected fields of contacts whoch registered in the specified time range

@param params [hash] hash of parameters according to emarsys API @return [Hash] result data @example

Emarsys::Contact.export_registrations(distribution_method: 'local', time_range: ["2013-01-01","2013-12-31"], contact_fields: [1,2,3])
# File lib/emarsys/data_objects/contact.rb, line 158
def export_registrations(distribution_method:, time_range:, contact_fields:, account: nil, **params)
  params.merge!(
    distribution_method: distribution_method,
    time_range: time_range,
    contact_fields: contact_fields
  )
  post account, "contact/getregistrations", params
end
query(return_value:, account: nil, **opts) click to toggle source

Query contacts by custom

@param return_value [Integer, String] Value of internal id field @param account [String] The account to use @param opts [Mixed] Further symbols to pass down to the request @return [Hash] result data @example

# Get all emails from the emarsys account
Emarsys::Contact.query(return_value: 'email')
# Get the ID of the account with a specific email
Emarsys::Contact.query(key_id: '_email', key_value: 'john.doe@example.com', return_value: 'email')
Emarsys::Contact.query(key_id: 3, key_value: 'jane.doe@example.com', return_value: 'email')
# File lib/emarsys/data_objects/contact.rb, line 139
def query(return_value:, account: nil, **opts)
  if opts.key?(:key_id) && opts.key?(:key_value)
    id, value = [opts.delete(:key_id), opts.delete(:key_value)]
    opts["#{transform_key_id(id).to_s}"] = value
  end

  opts = opts.each_with_object({}) do |(key, val), memo|
    memo[key.to_s] = val
  end

  get account, 'contact/query', opts.merge('return' => return_value)
end
transform_key_id(key_id) click to toggle source

@private

# File lib/emarsys/data_objects/contact.rb, line 168
def transform_key_id(key_id)
  matching_attributes = Emarsys::FieldMapping.attributes.find{|elem| elem[:identifier] == key_id.to_s}
  matching_attributes.nil? ? key_id : matching_attributes[:id]
end
update(key_id:, key_value:, params: {}, create_if_not_exists: false, account: nil) click to toggle source

Update a contact. The given params are transformed to emarsys ids.

@param key_id [Integer, String] internal id of key field @param key_value [Integer, String] value of internal id field @param params [Hash] Contact information to update @param create_if_not_exists [Boolean] Whether to create contact if it does not exist @return [Hash] internal id of the contact @example

Emarsys::Contact.update(key_id: 'app_id', key_value: 23, params: {:firstname => "Jon", :lastname => "Doe"})
Emarsys::Contact.update(key_id: '3', key_value: 'john.doe@example.com', params: {'1' => "Jon", '2' => "Doe"}, true)
# File lib/emarsys/data_objects/contact.rb, line 46
def update(key_id:, key_value:, params: {}, create_if_not_exists: false, account: nil)
  path = "contact#{create_if_not_exists ? '/?create_if_not_exists=1' : ''}"
  transformed_key_id = transform_key_id(key_id)
  put account, path, params.merge!({'key_id' => transformed_key_id, transformed_key_id => key_value})
end
update_batch(key_id:, params: [], create_if_not_exists: false, account: nil) click to toggle source

Batch update of contacts.

@param key_id [Integer, String] internal id of key field @param params [Hash] Contact information of each new contact @param create_if_not_exists [Boolean] Whether to create non-existing contacts @example

Emarsys::Contact.update_batch(
  key_id: 'email',
  params: [
    {:email => "john@example.com", :firstname => "Jon", :lastname => "Doe"},
    {:email => "jane@example.com", :firstname => "Jane", :lastname => "Doe"}
  ],
  create_if_not_exists: true
)
# File lib/emarsys/data_objects/contact.rb, line 84
def update_batch(key_id:, params: [], create_if_not_exists: false, account: nil)
  path = "contact#{create_if_not_exists ? '/?create_if_not_exists=1' : ''}"
  put account, path, {'key_id' => transform_key_id(key_id), 'contacts' => batch_params(params)}
end