Skip to main content

​
Overview

The Contacts resource allows you to import, update, and delete contacts in your Brew audience. Access it via client.contacts.

​
Methods

MethodDescription
contacts.import.create()Bulk import contacts
contacts.import.getStatus()Check import job status
contacts.update()Update a contact by email
contacts.delete()Delete a contact or specific fields

​
Import Contacts

Import multiple contacts into your Brew audience. Contacts are queued for processing and can optionally trigger automations.

​
Basic Import

import BrewSDK from 'brew-sdk';

const client = new BrewSDK();

const result = await client.contacts.import.create({
  contacts: [
    { email: '[email protected]' },
    { email: '[email protected]' },
  ],
});

console.log(result.data.stats);
// { total: 2, valid: 2, invalid: 0 }

​
Import with Full Contact Data

const result = await client.contacts.import.create({
  contacts: [
    {
      email: '[email protected]',
      firstName: 'John',
      lastName: 'Doe',
      subscribed: true,
      customFields: {
        company: 'Acme Inc',
        role: 'Developer',
        signupDate: '2024-01-15',
      },
    },
    {
      email: '[email protected]',
      firstName: 'Jane',
      lastName: 'Smith',
      subscribed: true,
      customFields: {
        company: 'Tech Corp',
        role: 'Designer',
      },
    },
  ],
  triggerAutomations: true,
});

​
Parameters

​
contacts
Contact[]
required
Array of contact objects to import.
​
triggerAutomations
boolean
default:"false"
Whether to trigger automations for imported contacts.

​
Response

interface ImportCreateResponse {
  success: true;
  message?: string;
  data: {
    importId?: string;           // Job ID for status tracking
    stats?: {
      total?: number;            // Total contacts in request
      valid?: number;            // Valid contacts queued
      invalid?: number;          // Invalid contacts (validation errors)
    };
    errors?: Array<{             // First 10 validation errors
      index?: number;
      email?: string;
      error?: string;
    }>;
    automations?: {              // If triggerAutomations was true
      triggered?: number;
      evaluated?: number;
      errors?: string[];
      timedOut?: boolean;
    };
  };
  meta?: {
    requestId?: string;
  };
}

​
Get Import Status

Check the status of a previously submitted import job.

​
Get Specific Import Status

const status = await client.contacts.import.getStatus({
  importId: 'import_abc123',
});

console.log(status.data.import?.status);
// 'pending' | 'processing' | 'completed' | 'failed'

​
List Recent Imports

Omit importId to get a list of recent imports: 
const imports = await client.contacts.import.getStatus();

imports.data.imports?.forEach(imp => {
  console.log(`${imp.id}: ${imp.status} - ${imp.addedCount} added`);
});

​
Response

// Single import status
interface ImportStatusResponse {
  success: true;
  data: {
    import?: {
      id?: string;
      status?: 'pending' | 'processing' | 'completed' | 'failed';
      fileName?: string;
      totalRows?: number;
      processedRows?: number;
      addedCount?: number;
      updatedCount?: number;
      errorCount?: number;
      errorMessage?: string;
      createdAt?: number;
      updatedAt?: number;
    };
  };
}

// List of imports
interface ImportListResponse {
  success: true;
  data: {
    imports?: Array<{
      id?: string;
      status?: string;
      fileName?: string;
      totalRows?: number;
      processedRows?: number;
      addedCount?: number;
      updatedCount?: number;
      errorCount?: number;
      createdAt?: number;
      updatedAt?: number;
    }>;
  };
}

​
Update Contact

Update an existing contact’s information. Custom fields are merged with existing values (not replaced).

​
Basic Update

const updated = await client.contacts.update({
  email: '[email protected]',
  firstName: 'Johnny',
});

console.log(updated.data);

​
Update with Custom Fields

const updated = await client.contacts.update({
  email: '[email protected]',
  firstName: 'Johnny',
  lastName: 'Doe Jr.',
  customFields: {
    role: 'Senior Developer',
    department: 'Engineering',
    lastActivity: new Date().toISOString(),
  },
});

​
Trigger Automations on Update

const updated = await client.contacts.update({
  email: '[email protected]',
  customFields: {
    planType: 'Premium',
  },
  triggerAutomations: true,
});

// Check automation results
if (updated.data.automations) {
  console.log(`Triggered ${updated.data.automations.triggered} automations`);
}

​
Parameters

​
email
string
required
Email address of the contact to update (used as lookup key).
​
firstName
string
Updated first name.
​
lastName
string
Updated last name.
​
subscribed
boolean
Updated subscription status.
​
customFields
object
Custom fields to merge with existing values.
​
triggerAutomations
boolean
default:"false"
If true, triggers field_update automations for changed fields.

​
Protected Fields

The following fields cannot be updated:
  • email (used as lookup key)
  • createdAt
  • updatedAt

​
Response

interface ContactUpdateResponse {
  success: true;
  data: {
    email?: string;
    firstName?: string;
    lastName?: string;
    subscribed?: boolean;
    customFields?: { [key: string]: unknown };
    createdAt?: number;       // Unix timestamp in milliseconds
    updatedAt?: number;       // Unix timestamp in milliseconds
    automations?: {           // Only if triggerAutomations was true
      triggered?: number;
      errors?: string[];
    };
  };
  meta?: {
    requestId?: string;
  };
}

​
Delete Contact

Delete a contact entirely or remove specific custom fields.

​
Delete Entire Contact

const result = await client.contacts.delete({
  email: '[email protected]',
});

console.log(result.data);
// { deleted: true, email: '[email protected]' }

​
Delete Specific Fields

Remove only specific custom fields from a contact: 
const result = await client.contacts.delete({
  email: '[email protected]',
  deleteFields: ['company', 'role'],
});

console.log(result.data);
// { deletedFields: ['company', 'role'], missingFields: [] }

​
Parameters

​
email
string
required
Email address of the contact.
​
deleteFields
string[]
Specific custom fields to delete. If omitted, deletes the entire contact.Note: Standard fields (firstName, lastName, subscribed, tags) cannot be deleted.

​
Response

// When deleting entire contact
interface DeleteContactResponse {
  success: true;
  data: {
    deleted?: true;
    email?: string;
  };
}

// When deleting specific fields
interface DeleteFieldsResponse {
  success: true;
  data: {
    deletedFields?: string[];
    missingFields?: string[];   // Fields that didn't exist
  };
}

​
Type Definitions

Import types for better TypeScript support: 
import BrewSDK from 'brew-sdk';

// Parameter types
type ImportCreateParams = BrewSDK.Contacts.ImportCreateParams;
type ImportGetStatusParams = BrewSDK.Contacts.ImportGetStatusParams;
type ContactUpdateParams = BrewSDK.ContactUpdateParams;
type ContactDeleteParams = BrewSDK.ContactDeleteParams;

// Response types
type ImportCreateResponse = BrewSDK.Contacts.ImportCreateResponse;
type ImportGetStatusResponse = BrewSDK.Contacts.ImportGetStatusResponse;
type ContactUpdateResponse = BrewSDK.ContactUpdateResponse;
type ContactDeleteResponse = BrewSDK.ContactDeleteResponse;

​
Error Handling

import BrewSDK from 'brew-sdk';

const client = new BrewSDK();

try {
  await client.contacts.update({
    email: '[email protected]',
    firstName: 'Test',
  });
} catch (error) {
  if (error instanceof BrewSDK.NotFoundError) {
    console.error('Contact not found');
  } else if (error instanceof BrewSDK.BadRequestError) {
    console.error('Invalid request:', error.message);
  } else {
    throw error;
  }
}

​
Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.