> ## 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
> CompanyEmail is a soft-deletable pivot (bridge) entity that links a Company to an Email address within the same workspace
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
```json theme={null}
{
"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" }
}
}
}
}
```
Source: `apps/api/src/database/entities/CompanyEmail.ts` ยท domain: financial-graph ยท tier: Supporting