Contacts API

Manage your contact database programmatically. Requires an API key with the contacts scope.

Base: https://mail.misar.io/api/v1/contacts

Endpoints

Method	Path	Description
GET	`/v1/contacts`	List contacts (paginated)
POST	`/v1/contacts`	Create a contact
PATCH	`/v1/contacts/:id`	Update a contact
DELETE	`/v1/contacts/:id`	Delete a contact
POST	`/v1/contacts/import`	Bulk import (Pro+)

GET /v1/contacts

List contacts with optional filtering.

Query Parameters

Param	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max 100)
`status`	string	—	Filter: `subscribed`, `unsubscribed`, `bounced`
`segment_id`	UUID	—	Filter by segment membership
`search`	string	—	Search by email or name

Response

{
  "success": true,
  "contacts": [
    {
      "id":         "550e8400-e29b-41d4-a716-446655440000",
      "email":      "user@example.com",
      "first_name": "Jane",
      "last_name":  "Doe",
      "status":     "subscribed",
      "tags":       ["customer", "vip"],
      "metadata":   { "plan": "pro" },
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1, "per_page": 50, "total": 1234, "total_pages": 25
  }
}

POST /v1/contacts

Create a single contact. Plan contact limits apply.

Request Body

{
  "email":      "user@example.com",
  "first_name": "Jane",
  "last_name":  "Doe",
  "tags":       ["customer"],
  "metadata":   { "plan": "pro" },
  "status":     "subscribed"
}

Field	Required	Notes
`email`	✓	Must be a valid email address
`first_name`	—
`last_name`	—
`tags`	—	Up to 20 tags
`metadata`	—	Custom key-value data
`status`	—	`subscribed` (default) or `unsubscribed`

Response

{
  "success": true,
  "contact": { "id": "...", "email": "user@example.com" }
}

Errors

403 — Contact limit reached for your plan
409 — Email already exists in your contacts

PATCH /v1/contacts/:id

Update a contact. Only the fields you provide are changed.

{
  "first_name": "Jane",
  "tags":       ["customer", "vip"],
  "status":     "unsubscribed"
}

DELETE /v1/contacts/:id

Permanently delete a contact and remove them from all segments.

{ "success": true }

POST /v1/contacts/import

Bulk import contacts from JSON or CSV. Available on Pro plan and above.

JSON Import

{
  "contacts": [
    { "email": "alice@example.com", "first_name": "Alice", "tags": ["newsletter"] },
    { "email": "bob@example.com",   "first_name": "Bob" }
  ],
  "update_existing": true
}

CSV Import

Send Content-Type: text/csv with a CSV body:

email,first_name,last_name,tags
alice@example.com,Alice,Smith,newsletter
bob@example.com,Bob,Jones,

Response

{
  "success":  true,
  "imported": 1842,
  "updated":  143,
  "skipped":  15,
  "errors": [
    { "row": 3, "email": "invalid-email", "error": "Invalid email format" }
  ]
}

Errors

403 — Bulk import not available on Free plan
403 — Contact limit would be exceeded by this import
400 — Invalid CSV format or missing email column