Contacts

Contacts store recipient information — email addresses, phone numbers, names, tags, and custom metadata. Use them to track who you're messaging and organize your audience.

Creating contacts

Every contact needs at least an email or a phone number:

await connect.contact.create({
  email: "alice@example.com",
  phone: "+15551234567",
  name: "Alice Johnson",
  tags: ["newsletter", "beta"],
  metadata: { plan: "pro", source: "signup-form" },
});

Tags and metadata

• Tags are string labels for grouping contacts (e.g. ["vip", "eu-region"])
• Metadata is a freeform JSON object for storing any extra data (e.g. plan, signup source, external IDs)

Both can be used to filter contacts when listing:

const vips = await connect.contact.list({
  tags: ["vip"],
  hasEmail: true,
  limit: 100,
  offset: 0,
});

Bulk import

Import up to 1,000 contacts in a single call:

await connect.contact.bulkCreate({
  contacts: [
    { email: "alice@example.com", name: "Alice" },
    { email: "bob@example.com", name: "Bob" },
  ],
  onDuplicate: "update",
});

Duplicates are detected by email or phone number. Set onDuplicate to "skip" to ignore existing contacts, or "update" to overwrite them.

Using contacts with messages

When sending a message, pass contactId to associate it with a contact:

await connect.message.send({
  channelType: "email",
  emailDomainId: "dom_...",
  to: "alice@example.com",
  subject: "Hey Alice",
  body: "<p>News for you.</p>",
  contactId: "ct_...",
});

Segments

Use segments to define reusable filter criteria over your contacts — for example, "all contacts with an email and the vip tag."