Contacts API

Store subscribers, subscription state, custom properties, and manual segments for broadcast targeting.

Contact Object

json

{
  "object": "contact",
  "id": "clx_contact123",
  "email": "[email protected]",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "created_at": "2026-04-30T12:00:00.000Z",
  "unsubscribed": false,
  "segments": [
    { "id": "seg_product", "name": "Product updates", "color": "#10b981" }
  ],
  "properties": {
    "company": "Acme",
    "plan": "pro"
  }
}

POST/v1/contacts

Create a global contact for the current account. The endpoint accepts Resend-compatible camelCase or snake_case name fields.

Request Body

json

{
  "email": "[email protected]",
  "firstName": "Steve",
  "lastName": "Wozniak",
  "unsubscribed": false,
  "segment_ids": ["seg_product"],
  "properties": { "company": "Acme" }
}

Response

json

{
  "object": "contact",
  "id": "clx_contact123"
}

bash

curl -X POST https://smtpfa.st/api/v1/contacts \
  -H "Authorization: Bearer sf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Steve",
    "lastName": "Wozniak",
    "unsubscribed": false,
    "segment_ids": ["seg_product"],
    "properties": { "company": "Acme" }
  }'

POST/v1/contacts

Import or upsert up to 500 contacts at once by sending a contacts array. Existing contacts are matched by email and updated in place.

Request Body

json

{
  "contacts": [
    {
      "email": "[email protected]",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "properties": { "plan": "growth" }
    },
    {
      "email": "[email protected]",
      "first_name": "Grace",
      "last_name": "Hopper",
      "unsubscribed": true
    }
  ],
  "segment_ids": ["seg_product"]
}

Response

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "clx_contact123",
      "email": "[email protected]",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "created_at": "2026-04-30T12:00:00.000Z",
      "unsubscribed": false,
      "disposable": false
    }
  ]
}

GET/v1/contacts

Returns contacts in newest-first order. Use optional q, status, segment_id, disposable, and limit query parameters for dashboard-style filtering. Every contact carries a disposable flag, true when the address is on a throwaway-mailbox domain.

Parameters

Parameter	Type	Required	Description
q	string	No	Search by email, first name, or last name
status	string	No	all, subscribed, or unsubscribed
segment_id	string	No	Return only contacts assigned to this manual segment
disposable	boolean	No	true returns only contacts on throwaway-mailbox domains, false only the rest
limit	number	No	Number of contacts to return, up to 100

Response

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "clx_contact123",
      "email": "[email protected]",
      "first_name": "Steve",
      "last_name": "Wozniak",
      "created_at": "2026-04-30T12:00:00.000Z",
      "unsubscribed": false,
      "disposable": false
    }
  ]
}

GET/v1/segments

List manual contact segments for the current account. The response includes the plan limit so dashboards can show quota clearly.

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "seg_product",
      "name": "Product updates",
      "description": "Customers who want release notes",
      "color": "#10b981",
      "contact_count": 128,
      "created_at": "2026-05-05T12:00:00.000Z"
    }
  ],
  "total": 1,
  "segment_limit": 10,
  "tier": "starter"
}

POST/v1/segments

Create a manual segment for organizing contacts and targeting broadcasts. Free accounts include 2 segments, Starter includes 10, Growth includes 50, and Scale includes 200.

Request Body

json

{
  "name": "Product updates",
  "description": "Customers who want release notes",
  "color": "#10b981"
}

Response

json

{
  "object": "segment",
  "id": "seg_product",
  "name": "Product updates",
  "contact_count": 0
}

GET/v1/segments/:id/contacts

List contacts assigned to a manual segment. Pagination uses the same page and limit parameters as the contacts list.

GET/v1/contacts/export?format=csv

Export up to 10,000 contacts as CSV or JSON. Pass status=subscribed, status=unsubscribed or disposable=true to export a filtered list.

GET/v1/contacts/:id

Retrieve a contact by ID or URL-encoded email address.

PATCH/v1/contacts/:id

Update name fields, subscription status, custom properties, or segment membership. Email addresses are immutable.

Request Body

json

{
  "unsubscribed": true,
  "segment_ids": ["seg_product"]
}

Response

json

{
  "object": "contact",
  "id": "clx_contact123"
}

bash

curl -X PATCH https://smtpfa.st/api/v1/contacts/steve%40example.com \
  -H "Authorization: Bearer sf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "unsubscribed": true, "segment_ids": ["seg_product"] }'

DELETE/v1/contacts/:id

Delete a contact by ID or URL-encoded email address.

Response

json

{
  "object": "contact",
  "contact": "clx_contact123",
  "deleted": true
}