Contacts & Accounts

Contacts represent the people you email. Each contact belongs to a tenant and can optionally be associated with an account (company).

Sync contacts

Bulk upsert contacts into your tenant. Existing contacts are matched by email and updated; new contacts are created.

POST https://api.molted.email/v1/contacts/sync

curl

curl -X POST https://api.molted.email/v1/contacts/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "contacts": [
      {
        "email": "jane@acme.com",
        "name": "Jane Smith",
        "ownerEmail": "rep@yourco.com",
        "lifecycleStage": "customer",
        "dealStage": "closed_won",
        "accountId": "acc_123",
        "metadata": { "plan": "enterprise", "region": "us-west" }
      }
    ]
  }'

List contacts

molted contacts list

Filter by email:

molted contacts list --email jane@acme.com

Flag	Type	Required	Description
`--email`	`string`	No	Filter by exact email address.

GET https://api.molted.email/v1/contacts

curl

curl "https://api.molted.email/v1/contacts?tenantId=tenant_abc123&email=jane@acme.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`email`	`string`	No	Filter by exact email address.

Response

Returns an array of contact objects. Returns up to 100 contacts, ordered by most recently updated.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_abc123",
    "email": "jane@acme.com",
    "name": "Jane Smith",
    "owner_email": "rep@yourco.com",
    "lifecycle_stage": "customer",
    "deal_stage": "closed_won",
    "account_id": "acc_123",
    "metadata": { "plan": "enterprise", "region": "us-west" },
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  }
]

If you have no contacts yet, the response is an empty array:

Empty response

[]

No contacts yet? Contacts are created automatically when you send your first email. You can also bulk-import contacts with molted contacts sync. See syncing contacts above.

Get contact by ID

GET https://api.molted.email/v1/contacts/:id

curl

curl https://api.molted.email/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "tenant_abc123",
  "email": "jane@acme.com",
  "name": "Jane Smith",
  "owner_email": "rep@yourco.com",
  "lifecycle_stage": "customer",
  "deal_stage": "closed_won",
  "account_id": "acc_123",
  "metadata": { "plan": "enterprise", "region": "us-west" },
  "created_at": "2026-03-01T12:00:00Z",
  "updated_at": "2026-03-01T12:00:00Z"
}

Contact model

Field	Type	Description
`id`	`string`	Unique contact identifier.
`tenant_id`	`string`	Tenant this contact belongs to.
`email`	`string`	Contact's email address.
`name`	`string`	Display name.
`owner_email`	`string`	Email of the assigned owner (e.g., sales rep).
`lifecycle_stage`	`string`	Current lifecycle stage (e.g., `lead`, `customer`).
`deal_stage`	`string`	Current deal stage (e.g., `qualified`, `closed_won`).
`account_id`	`string`	Associated account identifier.
`metadata`	`object`	Arbitrary key-value pairs for custom data.

Updating contacts

There is no individual update endpoint. To update contact data, use the POST /v1/contacts/sync endpoint with the updated fields — existing contacts are matched by email and merged.

Accounts represent companies or organizations. Contacts can be linked to an account via the accountId field. Accounts are created automatically when contacts are synced with an account association, or can be managed through your CRM integration.

On this page