Class: Sendly::ContactsResource

Inherits:
Object
  • Object
show all
Defined in:
lib/sendly/contacts_resource.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ ContactsResource

Returns a new instance of ContactsResource.



155
156
157
158
 
# File 'lib/sendly/contacts_resource.rb', line 155

def initialize(client)
  @client = client
  @lists = ContactListsResource.new(client)
end

Instance Attribute Details

#lists ⇒ Object (readonly)

Returns the value of attribute lists.



153
154
155
 
# File 'lib/sendly/contacts_resource.rb', line 153

def lists
  @lists
end

Instance Method Details

#bulk_mark_valid(ids: nil, list_id: nil) ⇒ Hash

Clear the invalid flag on many contacts at once — the escape hatch for when auto-flag misclassifies at scale. Pass either an explicit id array (up to 10,000 per call) OR a list_id, not both. Foreign ids silently no-op via the per-organization filter.

Parameters:

  • ids (Array<String>, nil) (defaults to: nil) —

    Explicit contact ids to clear

  • list_id (String, nil) (defaults to: nil) —

    Clear every flagged member of this list

Returns:

  • (Hash) —

    ‘{ cleared: Integer }` — number of contacts whose flag was actually cleared. Already-clean contacts and foreign ids don’t count.



224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/sendly/contacts_resource.rb', line 224

def bulk_mark_valid(ids: nil, list_id: nil)
  if ids.nil? && list_id.nil?
    raise ArgumentError, "bulk_mark_valid requires either :ids or :list_id"
  end
  if ids && list_id
    raise ArgumentError, "bulk_mark_valid accepts :ids OR :list_id, not both"
  end

  body = ids ? { ids: ids } : { listId: list_id }
  response = @client.post("/contacts/bulk-mark-valid", body)
  { cleared: response["cleared"] || 0 }
end

#check_numbers(list_id: nil, force: false) ⇒ Object

Trigger a background carrier lookup across your contacts. Landlines and other non-SMS-capable numbers are auto-excluded from future campaigns. The lookup runs asynchronously (1-5 minutes). Options: list_id (scope to a single list), force (re-check already-looked-up)



241
242
243
 
# File 'lib/sendly/contacts_resource.rb', line 241

def check_numbers(list_id: nil, force: false)
  @client.post("/contacts/lookup", { listId: list_id, force: force })
end

#create(phone_number:, name: nil, email: nil, metadata: nil) ⇒ Object 



182
183
184
185
186
187
188
189
190
 
# File 'lib/sendly/contacts_resource.rb', line 182

def create(phone_number:, name: nil, email: nil, metadata: nil)
  body = { phone_number: phone_number }
  body[:name] = name if name
  body[:email] = email if email
  body[:metadata] = metadata if metadata

  response = @client.post("/contacts", body)
  Contact.new(response)
end

#delete(id) ⇒ Object 



202
203
204
 
# File 'lib/sendly/contacts_resource.rb', line 202

def delete(id)
  @client.delete("/contacts/#{id}")
end

#get(id) ⇒ Object 



177
178
179
180
 
# File 'lib/sendly/contacts_resource.rb', line 177

def get(id)
  response = @client.get("/contacts/#{id}")
  Contact.new(response)
end

#import_contacts(contacts, list_id: nil, opted_in_at: nil) ⇒ Object 



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/sendly/contacts_resource.rb', line 245

def import_contacts(contacts, list_id: nil, opted_in_at: nil)
  body = {
    contacts: contacts.map { |c|
      h = { phone: c[:phone] }
      h[:name] = c[:name] if c[:name]
      h[:email] = c[:email] if c[:email]
      h[:optedInAt] = c[:opted_in_at] if c[:opted_in_at]
      h
    }
  }
  body[:listId] = list_id if list_id
  body[:optedInAt] = opted_in_at if opted_in_at

  response = @client.post("/contacts/import", body)
  {
    imported: response["imported"],
    skipped_duplicates: response["skippedDuplicates"],
    errors: response["errors"] || [],
    total_errors: response["totalErrors"] || 0
  }
end

#list(limit: nil, offset: nil, search: nil, list_id: nil) ⇒ Object 



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/sendly/contacts_resource.rb', line 160

def list(limit: nil, offset: nil, search: nil, list_id: nil)
  params = {}
  params[:limit] = limit if limit
  params[:offset] = offset if offset
  params[:search] = search if search
  params[:list_id] = list_id if list_id

  response = @client.get("/contacts", params)
  contacts = (response["contacts"] || []).map { |c| Contact.new(c) }
  {
    contacts: contacts,
    total: response["total"],
    limit: response["limit"],
    offset: response["offset"]
  }
end

#mark_valid(id) ⇒ Object

Clear the invalid flag on a contact so future campaigns include it again. Contacts get auto-flagged when a send fails with a terminal bad-number error (landline, invalid number) or when a carrier lookup reports they can’t receive SMS.



210
211
212
213
 
# File 'lib/sendly/contacts_resource.rb', line 210

def mark_valid(id)
  response = @client.post("/contacts/#{id}/mark-valid", {})
  Contact.new(response)
end

#update(id, name: nil, email: nil, metadata: nil) ⇒ Object 



192
193
194
195
196
197
198
199
200
 
# File 'lib/sendly/contacts_resource.rb', line 192

def update(id, name: nil, email: nil, metadata: nil)
  body = {}
  body[:name] = name unless name.nil?
  body[:email] = email unless email.nil?
  body[:metadata] = metadata unless metadata.nil?

  response = @client.patch("/contacts/#{id}", body)
  Contact.new(response)
end