Features

Contacts

Manage your email contacts and lists

Overview

Contacts are the people you send emails to. Each contact has an email address and optional metadata like name, company, and notes. Contacts can be organized into groups for targeted sends and campaigns.

You can manage contacts through the dashboard UI or programmatically via the API. Duplicate emails are automatically prevented at the database level.

List Contacts

Retrieve all contacts with optional filtering by group or search query. Results include group membership information for each contact.

GET/api/contacts

List all contacts with optional filtering by group or search term.

Parameters

Name	Type	Description
`search`	string	Filter by email or name (partial match)
`groupId`	number	Filter by group ID

Response

json

{
  "contacts": [
    {
      "id": 1,
      "email": "jane@example.com",
      "name": "Jane Smith",
      "company": "Acme Inc",
      "notes": null,
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "group_names": "Newsletter,VIP"
    }
  ]
}

Create Contact

Add a new contact. The email field is required and must be unique. You can optionally assign the contact to one or more groups at creation time.

POST/api/contacts

Create a new contact. Returns the new contact ID.

Parameters

Name	Type	Description
`email`*	string	Contact email address (must be unique)
`name`	string	Full name
`company`	string	Company or organization
`notes`	string	Freeform notes
`groupIds`	number[]	Array of group IDs to assign

Request

json

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "company": "Acme Inc",
  "notes": "Met at conference",
  "groupIds": [1, 3]
}

Response

json

{
  "id": 42
}

Update Contact

Update one or more fields on an existing contact. Only include the fields you want to change. The updated_at timestamp is set automatically.

PUT/api/contacts/[id]

Update a contact by ID. Send only the fields to change.

Parameters

Name	Type	Description
`email`	string	New email address
`name`	string	Updated name
`company`	string	Updated company
`notes`	string	Updated notes
`status`	string	"active", "unsubscribed", or "bounced"

Request

json

{
  "name": "Jane Doe",
  "status": "unsubscribed"
}

Response

json

{
  "success": true
}

Import Contacts

Bulk import contacts from a JSON array. Contacts with duplicate email addresses are silently skipped. The response tells you how many were imported vs. skipped.

POST/api/contacts/import

Bulk import contacts. Duplicates are skipped automatically.

Parameters

Name	Type	Description
`contacts`*	array	Array of contact objects with email, name, and company fields

Request

json

{
  "contacts": [
    { "email": "alice@example.com", "name": "Alice", "company": "WidgetCo" },
    { "email": "bob@example.com", "name": "Bob" },
    { "email": "carol@example.com" }
  ]
}

Response

json

{
  "success": true,
  "imported": 2,
  "total": 3,
  "skipped": 1
}

Export Contacts

Download all contacts as a CSV file. The export includes email, name, company, notes, status, and creation date. The response is served with a Content-Disposition header for direct file download.

GET/api/contacts/export

Export all contacts as a CSV file download.

Response

json

email,name,company,notes,status,created_at
jane@example.com,Jane Smith,Acme Inc,,active,2025-01-15
bob@example.com,Bob,,Notes here,active,2025-01-14

Authentication Templates