Contact Books

Organize contacts into groups, track statistics, and manage your contact lists with the Contact Books API.

Overview

Contact Books allow you to organize your contacts into logical groups (e.g., newsletters, VIP customers, product updates). Each contact book can have custom properties, emojis for easy identification, and detailed statistics about your contacts.

Base URL

https://api.unsent.dev/v1/contactBooks

Features

Organization

Group contacts into logical lists with custom names and emojis

Custom Properties

Store custom key-value metadata for each contact book

Statistics

Track total contacts, unsubscribed contacts, and associated campaigns

Contact Count

View subscriber counts for each contact book

Endpoints

List Contact Books

Retrieve all contact books for your team. Returns basic information including contact counts.

Endpoint: GET /v1/contactBooks

Response Schema

Field	Type	Description
`id`	`string`	Unique identifier for the contact book
`name`	`string`	Name of the contact book
`emoji`	`string`	Emoji icon for the contact book
`teamId`	`string`	ID of the team that owns this contact book
`properties`	`object`	Custom key-value properties
`createdAt`	`string`	ISO 8601 timestamp when created
`updatedAt`	`string`	ISO 8601 timestamp when last updated
`_count.contacts`	`number`	Total number of contacts in this book

Response Example

[
  {
    "id": "clxy123abc",
    "name": "Newsletter Subscribers",
    "emoji": "📰",
    "teamId": "team_abc123",
    "properties": {
      "source": "website",
      "segment": "engaged"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:45:00.000Z",
    "_count": {
      "contacts": 1523
    }
  },
  {
    "id": "clxy456def",
    "name": "VIP Customers",
    "emoji": "⭐",
    "teamId": "team_abc123",
    "properties": {},
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-18T16:20:00.000Z",
    "_count": {
      "contacts": 87
    }
  }
]

cURL Example

curl -X GET "https://api.unsent.dev/v1/contactBooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Create Contact Book

Create a new contact book to start organizing your contacts.

Endpoint: POST /v1/contactBooks

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Name of the contact book (minimum 1 character)
`emoji`	`string`	No	Emoji icon for visual identification
`properties`	`object`	No	Custom key-value metadata (string to string mapping)

[!NOTE] Currently, the API only uses the name field when creating contact books. The emoji and properties fields are accepted in the request but may not be persisted depending on the service implementation.

Response Schema

Field	Type	Description
`id`	`string`	Unique identifier for the created contact book
`name`	`string`	Name of the contact book
`emoji`	`string`	Emoji icon
`teamId`	`string`	ID of the team that owns this contact book
`properties`	`object`	Custom key-value properties
`createdAt`	`string`	ISO 8601 timestamp when created
`updatedAt`	`string`	ISO 8601 timestamp when last updated

Request Example

{
  "name": "Product Updates",
  "emoji": "🚀",
  "properties": {
    "category": "product",
    "frequency": "weekly"
  }
}

Response Example

{
  "id": "clxy789ghi",
  "name": "Product Updates",
  "emoji": "🚀",
  "teamId": "team_abc123",
  "properties": {
    "category": "product",
    "frequency": "weekly"
  },
  "createdAt": "2024-01-25T09:15:00.000Z",
  "updatedAt": "2024-01-25T09:15:00.000Z"
}

cURL Example

curl -X POST "https://api.unsent.dev/v1/contactBooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Updates",
    "emoji": "🚀",
    "properties": {
      "category": "product",
      "frequency": "weekly"
    }
  }'

Get Contact Book

Retrieve detailed information about a specific contact book, including statistics about contacts and associated campaigns.

Endpoint: GET /v1/contactBooks/{id}

Path Parameters

Parameter	Type	Description
`id`	`string`	Unique identifier of the contact book

Response Schema

Field	Type	Description
`id`	`string`	Unique identifier for the contact book
`name`	`string`	Name of the contact book
`emoji`	`string`	Emoji icon
`teamId`	`string`	ID of the team that owns this contact book
`properties`	`object`	Custom key-value properties
`createdAt`	`string`	ISO 8601 timestamp when created
`updatedAt`	`string`	ISO 8601 timestamp when last updated
`details.totalContacts`	`number`	Total number of contacts in this book
`details.unsubscribedContacts`	`number`	Number of unsubscribed contacts
`details.campaigns`	`array`	List of campaigns associated with this contact book

Response Example

{
  "id": "clxy123abc",
  "name": "Newsletter Subscribers",
  "emoji": "📰",
  "teamId": "team_abc123",
  "properties": {
    "source": "website",
    "segment": "engaged"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:45:00.000Z",
  "details": {
    "totalContacts": 1523,
    "unsubscribedContacts": 47,
    "campaigns": [
      {
        "id": "camp_xyz123",
        "name": "Weekly Newsletter",
        "createdAt": "2024-01-16T12:00:00.000Z"
      }
    ]
  }
}

cURL Example

curl -X GET "https://api.unsent.dev/v1/contactBooks/clxy123abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Error Responses

404 Not Found: Contact book not found or doesn't belong to your team

{
  "code": "NOT_FOUND",
  "message": "Contact book not found"
}

Update Contact Book

Update the name, emoji, or custom properties of an existing contact book.

Endpoint: PATCH /v1/contactBooks/{id}

Path Parameters

Parameter	Type	Description
`id`	`string`	Unique identifier of the contact book to update

Request Body

All fields are optional. Only include the fields you want to update.

Field	Type	Required	Description
`name`	`string`	No	New name for the contact book
`emoji`	`string`	No	New emoji icon
`properties`	`object`	No	Updated custom key-value metadata

Response Schema

Field	Type	Description
`id`	`string`	Unique identifier of the updated contact book
`name`	`string`	Current name of the contact book

Request Example

{
  "name": "Premium Newsletter Subscribers",
  "emoji": "💎",
  "properties": {
    "source": "website",
    "segment": "premium"
  }
}

Response Example

{
  "id": "clxy123abc",
  "name": "Premium Newsletter Subscribers"
}

cURL Example

curl -X PATCH "https://api.unsent.dev/v1/contactBooks/clxy123abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Newsletter Subscribers",
    "emoji": "💎"
  }'

Error Responses

404 Not Found: Contact book not found or doesn't belong to your team

{
  "code": "NOT_FOUND",
  "message": "Contact book not found"
}

Delete Contact Book

Permanently delete a contact book and all its associations. This action cannot be undone.

Endpoint: DELETE /v1/contactBooks/{id}

Path Parameters

Parameter	Type	Description
`id`	`string`	Unique identifier of the contact book to delete

[!CAUTION] Deleting a contact book is permanent and cannot be undone. Make sure you want to delete this contact book before proceeding.

Response Schema

Field	Type	Description
`success`	`boolean`	`true` if deletion was successful

Response Example

{
  "success": true
}

cURL Example

curl -X DELETE "https://api.unsent.dev/v1/contactBooks/clxy123abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Error Responses

404 Not Found: Contact book not found or doesn't belong to your team

{
  "code": "NOT_FOUND",
  "message": "Contact book not found"
}

Common Use Cases

Creating a Segmented Contact List

# Create a contact book for your blog subscribers
curl -X POST "https://api.unsent.dev/v1/contactBooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Subscribers",
    "emoji": "📝",
    "properties": {
      "source": "blog",
      "interests": "technology"
    }
  }'

Monitoring Contact Book Growth

# Get detailed statistics for a contact book
curl -X GET "https://api.unsent.dev/v1/contactBooks/clxy123abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Updating Contact Book Metadata

# Update properties as your segmentation evolves
curl -X PATCH "https://api.unsent.dev/v1/contactBooks/clxy123abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "source": "blog",
      "interests": "technology",
      "engagement": "high"
    }
  }'

Contact Books

Organization

Custom Properties

Statistics

Contact Count

On this page