Skip to main content

​
Overview

Contact books let you group email recipients into organized lists. Each contact book holds contacts with email addresses, names, subscription status, and custom properties. Use contact books to manage mailing lists, segment audiences, or maintain recipient directories.

​
How It Works

  1. Create a contact book in the dashboard or via API with a name
  2. Add contacts individually or in bulk (up to 1000 at a time)
  3. Send emails to contacts using their stored information
  4. Manage subscriptions by toggling the subscribed flag per contact

​
Contact Book Object

A contact book is a named container for contacts: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user_uuid",
  "name": "Newsletter Subscribers",
  "contact_count": 142,
  "created_at": "2026-03-07T12:00:00Z",
  "updated_at": "2026-03-07T12:00:00Z"
}

​
Contact Object

Each contact belongs to a single contact book: 
{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "contact_book_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "subscribed": true,
  "properties": {
    "company": "Acme Inc",
    "plan": "pro"
  },
  "created_at": "2026-03-07T12:00:00Z",
  "updated_at": "2026-03-07T12:00:00Z"
}

​
Custom Properties

The properties field accepts arbitrary JSON key-value pairs, allowing you to store any metadata relevant to your use case: 
{
  "properties": {
    "company": "Acme Inc",
    "role": "engineer",
    "signup_source": "landing_page",
    "lifetime_value": 500
  }
}

​
Bulk Operations

For large lists, use the bulk endpoints to add or remove up to 1000 contacts in a single request. This is significantly faster than making individual API calls. 
// Bulk add contacts
await fetch('https://app.usesendi.com/api/contact-books/BOOK_ID/contacts/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify([
    { email: 'alice@example.com', firstName: 'Alice' },
    { email: 'bob@example.com', firstName: 'Bob' },
  ]),
});

​
Plan Limits

FeatureFreePro
Contact books2Unlimited
Total contacts200Unlimited

​
Searching & Pagination

The list contacts endpoint supports pagination and search:
  • page — Page number (default: 1)
  • limit — Results per page (default: 50)
  • search — Filter contacts by email or name

​
Managing Contacts via API

See the Contact Books API reference and Contacts API reference for full CRUD operations.