Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
CompanyEmail is a soft-deletable pivot (bridge) entity that links a Company to an Email address within the same workspace. Each row carries three metadata flags — is_primary, is_verify, and label — that characterize how the email relates to its parent company. The entity enforces a partial-unique constraint: at most one non-deleted row per company can carry is_primary = TRUE, preventing multiple primary emails on the same company. It has no public UUID of its own; it is accessed via the parent company’s relationship graph, not as a first-class API resource.
| Naming | Value |
|---|
| Object | CompanyEmail |
Resource type (JSON:API type) | company_email |
| Collection / records root | — (not a records root) |
| REST base | /v1/company-emails |
| Entity class | CompanyEmail |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/company-emails | 🟡 Planned |
| Retrieve | GET /v1/company-emails/{id} | 🟡 Planned |
| Create | POST /v1/company-emails | 🟡 Planned |
| Update | PATCH /v1/company-emails/{id} | 🟡 Planned |
| Delete | DELETE /v1/company-emails/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| is_primary | boolean | ✅ Yes | Partial-unique index uniq_company_emails_primary_company: only one row per company_pk may have is_primary = TRUE WHERE deleted_at IS NULL | true | false | Designates this as the primary email address for the company. At most one non-deleted record per company can be primary. Used by computed fields and by enrichment to surface the canonical contact email. |
| is_verify | boolean | ✅ Yes | NOT NULL (varchar(255) in raw DDL maps to boolean not null) | true | false | Indicates whether this email address has been verified (e.g. by an enrichment pass or user confirmation). Does not affect tenant access control. |
| label | string | ✅ Yes | varchar(255) NOT NULL | Free text; common values: ‘billing’, ‘support’, ‘general’, ‘sales’, ‘contact’ | Semantic tag describing the purpose of this email address for the company (e.g. billing, support). Stored as free text; no enum enforced at the DB layer. |
| created_at | 🔒 system — Date | ✅ Yes | timestamptz NOT NULL; set once via MikroORM onCreate hook | — | Timestamp when this company-email association was created. Set automatically at insert; never updated. |
| deleted_at | Date | null | ⚪ No | timestamptz NULL; soft-delete sentinel — all live queries must filter WHERE deleted_at IS NULL | — | Soft-delete timestamp. NULL means the record is active. When set, the row is logically removed: the partial-unique primary-email index ignores it, and Hasura RLS / repository queries filter it out. |
Relationships
| Name | Type | Required | Description |
|---|
| company | to-one (ManyToOne) | ✅ Yes | The Company this email belongs to. FK company_pk → core_api.companies.pk. Indexed together with deleted_at via idx_company_emails_company_deleted for Hasura array-relationship traversals. |
| email | to-one (ManyToOne) | ✅ Yes | The Email address record (atomic entity storing the email string). FK email_pk → core_api.emails.pk. Indexed via idx_company_emails_email. The actual address string is on the Email entity, not on this pivot. |
System-computed
- created_at — set once by MikroORM onCreate: () => new Date(); never updated afterward (note: no updated_at column on this entity).
- deleted_at — written by soft-delete cascades when the parent Company is soft-deleted; also written by service-layer cleanup when an Email association is explicitly removed.
- Partial-unique index uniq_company_emails_primary_company is maintained by the database engine; enforcement is automatic on INSERT/UPDATE WHERE deleted_at IS NULL AND is_primary IS TRUE.
- The entity has no public UUID (*_id column). It is not directly addressable via the public API; access is always through the parent company’s array relationship (e.g. company_emails on the Company resource).
- Provenance (source_workspace_connector_pk) is not tracked on this entity; rows are written by the enrichment pipeline, connector sync (via reconciliation persister), and direct service-layer mutations — the source is inferred from the parent Company’s sourceWorkspaceConnector if needed.
Example
{
"data": {
"type": "company_email",
"attributes": {
"is_primary": true,
"is_verify": true,
"label": "billing",
"created_at": "2025-09-14T10:22:00.000Z",
"deleted_at": null
},
"relationships": {
"company": {
"data": { "type": "company", "id": "a3f1bc2d-0001-4e88-9c1d-000000000001" }
},
"email": {
"data": { "type": "email", "id": "7e9d2a1c-0002-4b77-ab2e-000000000002" }
}
}
}
}
apps/api/src/database/entities/CompanyEmail.ts · domain: financial-graph · tier: Supporting
