Contacts

Contact fields

Every contact has built-in fields for common data and supports custom properties for any additional information you need to store.

Built-in fields

These fields are available on every contact:

Custom properties

Store additional data using custom properties. You define properties at the workspace level, and they become available on all contacts. Properties have three types:

• String – Text up to 255 characters
• Number – Decimal numbers
• Date – Stored as Unix timestamps in milliseconds

See Custom Properties for setup instructions.

Contact status

A contact's status determines whether they receive your emails. Kibamail tracks six statuses:

Statuses change automatically based on email events. A hard bounce sets the status to BOUNCED. A spam complaint sets it to COMPLAINED. You can manually change status for SUBSCRIBED, UNSUBSCRIBED, and ARCHIVED.

Managing contacts

Adding contacts

Create contacts in three ways:

• Dashboard – Go to Contacts → Add Contact and enter their email address.
• API – Send a POST request to /v1/contacts with the contact data.
• Forms – Embed a sign-up form on your website. See Forms.

Here's an API example:

curl -X POST https://api.kibamail.com/v1/contacts \
  -H "Authorization: Bearer kb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sarah@acme.com",
    "firstName": "Sarah",
    "lastName": "Chen",
    "topics": ["topic_newsletter", "topic_product_updates"],
    "properties": {
      "Company": "Acme Inc",
      "Plan": "Enterprise"
    }
  }'

See the Contacts API Reference for all options.

Importing contacts

Import contacts from a CSV file to migrate from another platform or add contacts in bulk.

1. Go to Contacts → Import
2. Upload your CSV file
3. Map CSV columns to contact fields
4. Choose which topics to subscribe imported contacts to
5. Start the import

During import, you can choose to update existing contacts if the email already exists, or skip duplicates. See Contact Imports for details.

Updating contacts

Update a contact's information through the dashboard or API. All fields except email are optional when updating.

curl -X PUT https://api.kibamail.com/v1/contacts/contact_abc123 \
  -H "Authorization: Bearer kb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Sarah",
    "properties": {
      "Plan": "Pro"
    }
  }'

Deleting contacts

Deleting a contact permanently removes their record and all associated data:

• Topic subscriptions
• Segment memberships
• Form submissions
• Automation run history

This action cannot be undone. If you need to keep the data but stop sending emails, change the contact's status to ARCHIVED instead.

Topics and subscriptions

Topics let contacts choose which types of emails they want to receive. A contact can subscribe to multiple topics. When you send a broadcast, you target a topic, and only contacts subscribed to that topic receive the email.

Each contact-topic relationship has its own subscription status (SUBSCRIBED or UNSUBSCRIBED). This is separate from the contact's overall status.

Example: A contact might be:

• Subscribed to "Product Updates" (receives product announcement emails)
• Unsubscribed from "Newsletter" (doesn't receive weekly newsletter)

See Topics to learn how to set up topics.

Segments

Segments group contacts based on their data. Use segments to target specific audiences with your broadcasts.

Kibamail supports two segment types:

• Dynamic segments – Automatically include contacts matching your conditions. As contact data changes, segment membership updates automatically.
• Static segments – Manually add contacts. Membership only changes when you explicitly add or remove contacts.

Filter contacts by any built-in field or custom property. Combine conditions with AND/OR logic.

See Segments to create your first segment.

Related

• Custom Properties – Define additional fields for your contacts
• Topics – Let contacts choose their email preferences
• Segments – Group contacts for targeted sending
• Contact Imports – Import contacts from CSV files
• Contacts API Reference – Full API documentation