Skip to main content

Contacts

Comprehensive contact management with full CRUD operations, bulk imports, tagging, and granular preference management.

Create Contact​

Create a new contact with comprehensive profile data.

const contact = await sendmator.contacts.create({
  external_id: 'CRM-001',           // Optional: Your system's ID
  email: 'user@example.com',        // Required
  first_name: 'John',               // Optional
  last_name: 'Doe',                 // Optional
  phone: '+14155552671',            // Optional
  tags: ['customer', 'vip'],        // Optional
  is_active: true,                  // Optional: Default true
  custom_fields: {                  // Optional: Any custom data
    company: 'Acme Corp',
    role: 'Developer',
    plan: 'Enterprise'
  },
  metadata: {                       // Optional: Tracking data
    source: 'website',
    campaign: 'newsletter'
  },
  preferences: {                    // Optional: Channel preferences
    email: {
      transactional: true,
      promotional: false,
      marketing: true
    }
  }
});

console.log('Contact ID:', contact.id);
console.log('External ID:', contact.external_id);

Auto-Generated External ID​

If you don't provide an external_id, one is automatically generated:

const contact = await sendmator.contacts.create({
  email: 'user@example.com',
  first_name: 'Jane'
});

// Response includes auto-generated UUID
console.log(contact.external_id); // "d137555d-ef5a-4cf5-ad59-2713204b8482"

Get Contact​

Get by ID​

const contact = await sendmator.contacts.get('contact-uuid');

Get by External ID​

Perfect for syncing with your existing systems:

const contact = await sendmator.contacts.getByExternalId('CRM-001');

List Contacts​

List contacts with powerful filtering, search, and pagination:

const result = await sendmator.contacts.list({
  page: 1,
  limit: 20,
  tags: ['customer', 'vip'],
  search: 'john',
  email: 'example.com',
  is_active: true,
  is_unsubscribed: false,
  sort_by: 'created_at',
  sort_order: 'DESC'
});

console.log('Total contacts:', result.total);
console.log('Total pages:', result.totalPages);
console.log('Contacts:', result.contacts);

Filter Parameters​

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20)
tagsstring[]Filter by tags (AND logic)
searchstringSearch in email, name, external_id
emailstringFilter by email pattern
is_activebooleanFilter by active status (default: true)
is_unsubscribedbooleanFilter by unsubscribed status
sort_bystringSort field: created_at, updated_at, email, first_name, last_name
sort_orderstringASC or DESC

Examples​

Search for contacts:

const result = await sendmator.contacts.list({
  search: 'john',
  limit: 10
});

Filter by tags:

const vipCustomers = await sendmator.contacts.list({
  tags: ['vip', 'customer'],
  is_active: true
});

Get inactive (deleted) contacts:

const deleted = await sendmator.contacts.list({
  is_active: false
});

Filter by email domain:

const gmailContacts = await sendmator.contacts.list({
  email: 'gmail.com'
});

Update Contact​

Update any contact fields. Only provided fields will be updated:

const updated = await sendmator.contacts.update('contact-uuid', {
  first_name: 'Jane',
  last_name: 'Smith',
  tags: ['customer', 'enterprise'],
  custom_fields: {
    company: 'New Corp',
    role: 'CTO',
    plan: 'Enterprise'
  }
});

Update External ID​

await sendmator.contacts.update('contact-uuid', {
  external_id: 'NEW-CRM-ID-123'
});

Delete Contact​

Soft Delete (Default)​

By default, contacts are soft-deleted (marked as inactive but kept in database):

// Soft delete - sets is_active = false
await sendmator.contacts.delete('contact-uuid');

Soft-deleted contacts:

  • Remain in database
  • Counted in stats
  • Not shown in default list view
  • Can be recovered by updating is_active = true

Hard Delete​

Permanently remove a contact from the database:

// Hard delete - permanently removes from database
await sendmator.contacts.delete('contact-uuid', true);
warning

Hard deletes cannot be undone. The contact is permanently removed from the database.

Bulk Create Contacts​

Create multiple contacts in a single request:

const result = await sendmator.contacts.bulkCreate({
  contacts: [
    {
      email: 'user1@example.com',
      first_name: 'User',
      last_name: 'One',
      tags: ['bulk-import']
    },
    {
      email: 'user2@example.com',
      first_name: 'User',
      last_name: 'Two',
      tags: ['bulk-import']
    },
    {
      email: 'user3@example.com',
      first_name: 'User',
      last_name: 'Three',
      tags: ['bulk-import']
    }
  ]
});

console.log('Total processed:', result.total_processed);
console.log('Created:', result.summary.created_count);
console.log('Skipped:', result.summary.skipped_count);
console.log('Errors:', result.summary.error_count);

// Access created contacts
result.created.forEach(contact => {
  console.log('Created:', contact.email);
});

// Check skipped (duplicates)
result.skipped.forEach(item => {
  console.log('Skipped:', item.email, '-', item.reason);
});

// Check errors
result.errors.forEach(item => {
  console.log('Error:', item.email, '-', item.error);
});

Tag Management​

Add Tags​

const contact = await sendmator.contacts.addTags('contact-uuid', [
  'premium',
  'early-adopter',
  'beta-tester'
]);

console.log('Updated tags:', contact.tags);

Remove Tags​

const contact = await sendmator.contacts.removeTags('contact-uuid', [
  'beta-tester'
]);

console.log('Remaining tags:', contact.tags);

Unsubscribe​

Mark a contact as unsubscribed (legacy method):

const contact = await sendmator.contacts.unsubscribe('contact-uuid');

console.log('Is unsubscribed:', contact.is_unsubscribed);
console.log('Unsubscribed at:', contact.unsubscribed_at);

Preference Management​

Sendmator provides granular preference management across 4 channels and 7 categories.

Channels​

  • email
  • sms
  • whatsapp
  • push

Categories​

  • transactional - Critical account/order updates
  • promotional - Sales and offers
  • utility - Product updates and tips
  • conversational - Interactive messages
  • marketing - Newsletters and campaigns
  • service - Support and help
  • system - System notifications

Get Preferences​

Get all preferences with statistics:

const prefs = await sendmator.contacts.getPreferences('contact-uuid');

console.log('Total preferences:', prefs.totalPreferences);
console.log('Subscribed count:', prefs.subscribedCount);
console.log('Subscription rate:', prefs.subscriptionRate + '%');

// Access preferences by channel
console.log('Email promotional:', prefs.preferences.email?.promotional);
console.log('SMS marketing:', prefs.preferences.sms?.marketing);

Update Single Preference​

Update one specific preference:

await sendmator.contacts.updateSinglePreference(
  'contact-uuid',
  'email',        // channel
  'promotional',  // category
  { subscribed: false }
);

Update Multiple Preferences​

Batch update preferences:

await sendmator.contacts.updatePreferences('contact-uuid', {
  preferences: [
    { channel: 'email', category: 'promotional', subscribed: false },
    { channel: 'email', category: 'marketing', subscribed: false },
    { channel: 'sms', category: 'promotional', subscribed: true },
    { channel: 'whatsapp', category: 'utility', subscribed: true }
  ]
});

Unsubscribe from Channel​

Unsubscribe from all categories in a specific channel:

// Unsubscribe from all email communications
await sendmator.contacts.unsubscribeChannel('contact-uuid', 'email');

Unsubscribe from All​

Unsubscribe from all channels and categories:

// Global unsubscribe
await sendmator.contacts.unsubscribeAll('contact-uuid');

Subscribe to All​

Re-subscribe to all channels and categories:

// Re-activate all preferences
await sendmator.contacts.subscribeAll('contact-uuid');

Complete Example​

import Sendmator from '@sendmator/node';

const sendmator = new Sendmator({
  apiKey: process.env.SENDMATOR_API_KEY,
});

async function manageContact() {
  // 1. Create contact
  const contact = await sendmator.contacts.create({
    external_id: 'CRM-12345',
    email: 'john.doe@example.com',
    first_name: 'John',
    last_name: 'Doe',
    phone: '+14155552671',
    tags: ['customer', 'trial'],
    custom_fields: {
      company: 'Acme Corp',
      plan: 'Pro',
      trial_ends: '2024-02-01'
    }
  });

  console.log('Created contact:', contact.id);

  // 2. Update contact
  await sendmator.contacts.update(contact.id, {
    tags: ['customer', 'paid'],
    custom_fields: {
      company: 'Acme Corp',
      plan: 'Enterprise',
      converted_at: '2024-01-15'
    }
  });

  // 3. Add tags
  await sendmator.contacts.addTags(contact.id, ['vip', 'power-user']);

  // 4. Set preferences
  await sendmator.contacts.updatePreferences(contact.id, {
    preferences: [
      { channel: 'email', category: 'promotional', subscribed: false },
      { channel: 'email', category: 'transactional', subscribed: true },
      { channel: 'email', category: 'utility', subscribed: true }
    ]
  });

  // 5. Get updated contact
  const updated = await sendmator.contacts.getByExternalId('CRM-12345');
  console.log('Updated contact:', updated);

  // 6. List similar contacts
  const similar = await sendmator.contacts.list({
    tags: ['customer', 'paid'],
    limit: 10
  });
  console.log('Found similar contacts:', similar.total);
}

manageContact().catch(console.error);

Error Handling​

import { SendmatorError } from '@sendmator/node';

try {
  await sendmator.contacts.create({
    email: 'duplicate@example.com'
  });
} catch (error) {
  if (error instanceof SendmatorError) {
    if (error.statusCode === 409) {
      console.log('Contact already exists');
    } else if (error.statusCode === 400) {
      console.log('Invalid data:', error.message);
    }
  }
}

Best Practices​

  1. Use External IDs - Always sync your system's IDs using external_id
  2. Soft Delete First - Use soft deletes to prevent accidental data loss
  3. Bulk Operations - Use bulk create for importing multiple contacts
  4. Tag Strategically - Use tags for segmentation and filtering
  5. Granular Preferences - Respect user preferences at channel+category level
  6. Error Handling - Always handle duplicate errors (409) gracefully
  7. Pagination - Use pagination for large contact lists
  8. Search Wisely - Combine filters for precise contact queries

Next Steps​