Contacts

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

Required scope: contacts

List contacts

GET /v1/contacts

Query params: status (active|unsubscribed|bounced|complained), search, segmentId, page, limit.

{
  "success": true,
  "data": [
    {
      "id": "con_01ABCDEF",
      "email": "[email protected]",
      "firstName": "Alice",
      "lastName": "Smith",
      "status": "active",
      "score": 82,
      "tags": ["customer", "vip"],
      "createdAt": "2025-01-15T08:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 3200 }
}

Get contact

GET /v1/contacts/:id

Create contact

POST /v1/contacts

{
  "email": "[email protected]",
  "firstName": "Alice",
  "lastName": "Smith",
  "tags": ["customer"],
  "metadata": {
    "plan": "pro",
    "signupSource": "landing-page"
  }
}

Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | ✅ | Contact email address | | firstName | string | — | First name | | lastName | string | — | Last name | | phone | string | — | Phone number | | tags | array | — | String labels | | metadata | object | — | Arbitrary key-value pairs | | status | string | — | active (default) | unsubscribed |

Update contact

PATCH /v1/contacts/:id

Accepts any subset of create fields. email cannot be changed.

Bulk update / delete

PATCH /v1/contacts/bulk
DELETE /v1/contacts/bulk

{
  "ids": ["con_01ABC", "con_02DEF"],
  "update": { "tags": ["churned"] }
}

Import contacts

POST /v1/contacts/import

Upload a JSON array of contacts (max 10 000 per request):

{
  "contacts": [
    { "email": "[email protected]", "firstName": "A" },
    { "email": "[email protected]", "firstName": "B" }
  ],
  "skipExisting": false,
  "tags": ["imported-june-2025"]
}

Response:

{
  "success": true,
  "imported": 1998,
  "skipped": 2,
  "failed": 0,
  "errors": []
}

Contact scoring

MisarMail automatically scores contacts 0–100 based on engagement. Higher = more engaged.

GET /v1/contacts/:id/score

{
  "score": 82,
  "tier": "champion",
  "factors": {
    "openRate": 0.71,
    "clickRate": 0.23,
    "recency": "3d",
    "frequency": "high"
  }
}

Scoring tiers

| Score | Tier | |-------|------| | 80–100 | Champion | | 60–79 | Loyal | | 40–59 | Potential | | 20–39 | At risk | | 0–19 | Dormant |

Scoring rules (custom)

GET /v1/contacts/scoring-rules
POST /v1/contacts/scoring-rules
PATCH /v1/contacts/scoring-rules/:id
DELETE /v1/contacts/scoring-rules/:id

List health

Run a deliverability health check to identify invalid, risky, or unengaged addresses:

POST /v1/contacts/health/run
GET  /v1/contacts/health/stats
GET  /v1/contacts/health/unengaged