Hi there,
Following up on our chat earlier this week.
", "valueType": "HTML" } }, "httpLink": null, "objectType": "email", "relationships": { "$account": { "cardinality": "has_many", "objectType": "account", "values": [ "acc_cm4stu901uvw234" ] }, "$contact": { "cardinality": "has_many", "objectType": "contact", "values": [ "con_cm2ghi789jkl012" ] } }, "updatedAt": "2026-05-01T10:00:00.000Z", "externalId": "externalId" } ``` ## List emails `$ lightfield email list` **get** `/v1/emails` Returns a paginated list of emails. Use `offset` and `limit` to paginate through results. Each email is privacy-filtered per caller, includes a read-only `accessLevel`, and may redact the subject at metadata-only access. `fields.$body` is not included on list items; use GET `/v1/emails/{id}` for message body HTML. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination. **[Required scope](/using-the-api/scopes/):** `emails:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Parameters - `--limit: optional number` Maximum number of records to return. Defaults to 25, maximum 25. - `--offset: optional number` Number of records to skip for pagination. Defaults to 0. ### Returns - `email_list_response: object { data, object, totalCount }` - `data: array of object { id, accessLevel, createdAt, 6 more }` Array of email objects for the current page. - `id: string` Unique identifier for the entity. - `accessLevel: "FULL" or "METADATA"` The caller's resolved access level for this email. - `"FULL"` - `"METADATA"` - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Field map for this email. Does not include `$body`; retrieve the email by ID for message HTML. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `union_member_0: string` - `union_member_1: number` - `union_member_2: boolean` - `union_member_3: array of string` - `Address: object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName: object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `objectType: "email"` Always `email`. - `"email"` - `relationships: map[object { cardinality, objectType, values } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Example ```cli lightfield email list \ --api-key 'My API Key' ``` #### Response ```json { "data": [ { "id": "eml_cm0abc456def789", "accessLevel": "FULL", "createdAt": "2026-05-01T09:00:00.000Z", "fields": { "$subject": { "value": "Following up on our chat", "valueType": "TEXT" }, "$sentAt": { "value": "2026-05-01T08:30:00.000Z", "valueType": "DATETIME" }, "$from": { "value": [ "sales@acme.com" ], "valueType": "EMAIL" }, "$to": { "value": [ "lead@example.com" ], "valueType": "EMAIL" }, "$cc": { "value": [ "string" ], "valueType": "EMAIL" }, "$bcc": { "value": [ "string" ], "valueType": "EMAIL" }, "$privacySetting": { "value": "string", "valueType": "TEXT" } }, "httpLink": null, "objectType": "email", "relationships": { "$account": { "cardinality": "has_many", "objectType": "account", "values": [ "acc_cm4stu901uvw234" ] }, "$contact": { "cardinality": "has_many", "objectType": "contact", "values": [ "con_cm2ghi789jkl012" ] } }, "updatedAt": "2026-05-01T10:00:00.000Z", "externalId": "externalId" }, { "id": "eml_cm1xyz123uvw456", "accessLevel": "METADATA", "createdAt": "2026-04-29T15:12:00.000Z", "fields": { "$subject": { "value": "string", "valueType": "TEXT" }, "$sentAt": { "value": "2026-04-29T15:11:30.000Z", "valueType": "DATETIME" }, "$from": { "value": [ "ceo@acme.com" ], "valueType": "EMAIL" }, "$to": { "value": [ "member@lightfield.com" ], "valueType": "EMAIL" }, "$cc": { "value": [ "string" ], "valueType": "EMAIL" }, "$bcc": { "value": [ "string" ], "valueType": "EMAIL" }, "$privacySetting": { "value": "string", "valueType": "TEXT" } }, "httpLink": null, "objectType": "email", "relationships": { "$account": { "cardinality": "has_many", "objectType": "account", "values": [ "acc_cm4stu901uvw234" ] } }, "updatedAt": "2026-04-29T15:12:00.000Z", "externalId": "externalId" } ], "object": "list", "totalCount": 2 } ``` ## Send an email `$ lightfield email send` **post** `/v1/emails/send` Sends an email via the connected email account that owns the `from` address. Currently supports new sends only; replies and forwards are not yet supported. Supports idempotency via the `Idempotency-Key` header. **[Required scope](/using-the-api/scopes/):** `emails:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `--from: string` Bare email address (no display name). Must match a connected email account owned by the API key user. Compared case-insensitively. Used as the From header when sending. - `--message-body: object { content, contentType }` Email message body (HTML or plain text). - `--subject: string` Email subject. Cannot be empty. - `--to: array of string` Recipient email addresses (bare, no display names). At least 1, at most 500. - `--attachment: optional array of string` Optional list of file IDs (uploaded via the Files API) to attach to the email. Maximum 5 attachments per email, each ≤ 3MB. - `--bcc: optional array of string` Bcc recipients (same shape as `to`). - `--cc: optional array of string` Cc recipients (same shape as `to`). ### Returns - `email_send_response: object { sentAt }` - `sentAt: string` ISO 8601 timestamp of when the send completed. ### Example ```cli lightfield email send \ --api-key 'My API Key' \ --from sales@acme.com \ --message-body "{content: 'Hi there,
Following up on our chat earlier this week.
'}" \ --subject 'Following up on our chat' \ --to lead@example.com ``` #### Response ```json { "sentAt": "sentAt" } ``` ## Create a draft email `$ lightfield email draft` **post** `/v1/emails/draft` Creates a draft in the connected email account that owns the `from` address. Mirrors native email-client behavior: only `from` is required — `to`, `cc`, `bcc`, `subject`, `messageBody`, and `attachments` are all optional. At least one of those optional fields must be populated; sending only `from` returns a 400. Supports idempotency via the `Idempotency-Key` header. **[Required scope](/using-the-api/scopes/):** `emails:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `--from: string` Bare email address (no display name). Must match a connected email account owned by the API key user. Compared case-insensitively. Mailbox where the draft is created. - `--attachment: optional array of string` Optional list of file IDs (uploaded via the Files API) to attach to the draft. Maximum 5 attachments per draft, each ≤ 3MB. - `--bcc: optional array of string` Bcc recipients (same shape as `to`). - `--cc: optional array of string` Cc recipients (same shape as `to`). - `--message-body: optional object { content, contentType }` Email message body (HTML or plain text). - `--subject: optional string` Email subject. - `--to: optional array of string` Recipient email addresses (bare, no display names). Up to 500. ### Returns - `email_draft_response: object { draftedAt }` - `draftedAt: string` ISO 8601 timestamp of when the draft was created. ### Example ```cli lightfield email draft \ --api-key 'My API Key' \ --from sales@acme.com ``` #### Response ```json { "draftedAt": "draftedAt" } ``` ## Domain Types ### Email Draft Response - `email_draft_response: object { draftedAt }` - `draftedAt: string` ISO 8601 timestamp of when the draft was created. ### Email List Response - `email_list_response: object { data, object, totalCount }` - `data: array of object { id, accessLevel, createdAt, 6 more }` Array of email objects for the current page. - `id: string` Unique identifier for the entity. - `accessLevel: "FULL" or "METADATA"` The caller's resolved access level for this email. - `"FULL"` - `"METADATA"` - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Field map for this email. Does not include `$body`; retrieve the email by ID for message HTML. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `union_member_0: string` - `union_member_1: number` - `union_member_2: boolean` - `union_member_3: array of string` - `Address: object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName: object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `objectType: "email"` Always `email`. - `"email"` - `relationships: map[object { cardinality, objectType, values } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Email Retrieve Response - `email_retrieve_response: object { id, accessLevel, createdAt, 6 more }` - `id: string` Unique identifier for the entity. - `accessLevel: "FULL" or "METADATA"` The caller's resolved access level for this email. - `"FULL"` - `"METADATA"` - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `union_member_0: string` - `union_member_1: number` - `union_member_2: boolean` - `union_member_3: array of string` - `Address: object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName: object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `objectType: "email"` Always `email`. - `"email"` - `relationships: map[object { cardinality, objectType, values } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. ### Email Send Response - `email_send_response: object { sentAt }` - `sentAt: string` ISO 8601 timestamp of when the send completed.