Lightfield Emails API
The Emails API from Lightfield — 4 operation(s) for emails.
OpenAPI Specification
openapi: 3.1.1
info:
title: API Reference Accounts Emails API
version: 0.0.0
tags:
- name: Emails
paths:
/v1/emails/{id}:
get:
operationId: email.retrieve
summary: Retrieve an email
description: 'Retrieves a single email by its ID. Email fields are redacted based on the caller-specific privacy resolution, and the response includes a read-only `accessLevel`.
**[Required scope](/using-the-api/scopes/):** `emails:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read'
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: id
in: path
required: true
schema:
type: string
description: Unique identifier of the email to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailRetrieveResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Emails
/v1/emails:
get:
operationId: email.list
summary: List emails
description: '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 <u>[List endpoints](/using-the-api/list-endpoints/)</u> for more information about pagination.
**[Required scope](/using-the-api/scopes/):** `emails:read`
**[Rate limit category](/using-the-api/rate-limits/):** Search'
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
- name: offset
in: query
schema:
type: integer
minimum: 0
maximum: 9007199254740991
description: Number of records to skip for pagination. Defaults to 0.
allowEmptyValue: true
allowReserved: true
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 9007199254740991
description: Maximum number of records to return. Defaults to 25, maximum 25.
allowEmptyValue: true
allowReserved: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailListResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Emails
/v1/emails/send:
post:
operationId: email.send
summary: Send an email
description: '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'
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
from:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
description: 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.
examples:
- sales@acme.com
to:
type: array
minItems: 1
maxItems: 500
items:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
examples:
- lead@example.com
description: Recipient email addresses (bare, no display names). At least 1, at most 500.
cc:
type: array
maxItems: 500
items:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
examples:
- lead@example.com
description: Cc recipients (same shape as `to`).
bcc:
type: array
maxItems: 500
items:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
examples:
- lead@example.com
description: Bcc recipients (same shape as `to`).
subject:
type: string
minLength: 1
description: Email subject. Cannot be empty.
examples:
- Following up on our chat
messageBody:
type: object
properties:
contentType:
enum:
- HTML
- TEXT
description: Defaults to `HTML`.
content:
type: string
minLength: 1
description: Email body content.
examples:
- <p>Hi there,</p><p>Following up on our chat earlier this week.</p>
required:
- content
additionalProperties: false
title: EmailMessageBody
description: Email message body (HTML or plain text).
examples:
- contentType: HTML
content: <p>Hi there,</p><p>Following up on our chat earlier this week.</p>
attachments:
type: array
maxItems: 5
items:
type: string
examples:
- file_01abc2def3ghi4jkl5mno6pqr
description: Optional list of file IDs (uploaded via the Files API) to attach to the email. Maximum 5 attachments per email, each ≤ 3MB.
required:
- from
- to
- subject
- messageBody
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSendResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Emails
/v1/emails/draft:
post:
operationId: email.draft
summary: Create a draft email
description: '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'
security:
- bearerAuth: []
parameters:
- name: Lightfield-Version
in: header
required: true
description: Required API version header. Requests may error without it.
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-01'
example: '2026-03-01'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
from:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
description: 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.
examples:
- sales@acme.com
to:
type: array
maxItems: 500
items:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
examples:
- lead@example.com
description: Recipient email addresses (bare, no display names). Up to 500.
cc:
type: array
maxItems: 500
items:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
examples:
- lead@example.com
description: Cc recipients (same shape as `to`).
bcc:
type: array
maxItems: 500
items:
type: string
pattern: ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
examples:
- lead@example.com
description: Bcc recipients (same shape as `to`).
subject:
type: string
description: Email subject.
messageBody:
type: object
properties:
contentType:
enum:
- HTML
- TEXT
description: Defaults to `HTML`.
content:
type: string
description: Email body content.
examples:
- <p>Hi there,</p><p>Following up on our chat earlier this week.</p>
required:
- content
additionalProperties: false
description: Email message body (HTML or plain text).
attachments:
type: array
maxItems: 5
items:
type: string
examples:
- file_01abc2def3ghi4jkl5mno6pqr
description: Optional list of file IDs (uploaded via the Files API) to attach to the draft. Maximum 5 attachments per draft, each ≤ 3MB.
required:
- from
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailDraftResponse'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'415':
description: '415'
content:
application/json:
schema:
$ref: '#/components/schemas/UnsupportedMediaTypeError'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableContentError'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'503':
description: '503'
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableError'
'504':
description: '504'
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
tags:
- Emails
components:
schemas:
EmailRetrieveResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the entity.
createdAt:
type: string
description: ISO 8601 timestamp of when the entity was created.
updatedAt:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp of when the entity was last updated, or null.
httpLink:
anyOf:
- type: string
- type: 'null'
description: URL to view the entity in the Lightfield web app, or null.
externalId:
anyOf:
- type: string
- type: 'null'
description: External identifier for the entity, or null if unset.
fields:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
valueType:
enum:
- ADDRESS
- CHECKBOX
- CURRENCY
- DATETIME
- EMAIL
- FULL_NAME
- MARKDOWN
- MULTI_SELECT
- NUMBER
- SINGLE_SELECT
- SOCIAL_HANDLE
- TELEPHONE
- TEXT
- URL
- HTML
description: The data type of the field.
value:
anyOf:
- type: string
- type: integer
minimum: -9007199254740991
maximum: 9007199254740991
- type: number
- type: boolean
- type: 'null'
- type: array
items:
type: string
- $ref: '#/components/schemas/Address'
- $ref: '#/components/schemas/FullName'
description: The field value, or null if unset.
required:
- valueType
- value
description: Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug.
relationships:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
cardinality:
type: string
description: Whether the relationship is `has_one` or `has_many`.
objectType:
type: string
description: The type of the related object (e.g. `account`, `contact`).
values:
type: array
items:
type: string
description: IDs of the related entities.
required:
- cardinality
- objectType
- values
description: Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`).
objectType:
enum:
- email
description: Always `email`.
accessLevel:
enum:
- FULL
- METADATA
description: The caller's resolved access level for this email.
required:
- id
- createdAt
- updatedAt
- httpLink
- fields
- relationships
- objectType
- accessLevel
additionalProperties: false
examples:
- id: eml_cm0abc456def789
createdAt: '2026-05-01T09:00:00.000Z'
updatedAt: '2026-05-01T10:00:00.000Z'
httpLink: null
fields:
$subject:
valueType: TEXT
value: Following up on our chat
$sentAt:
valueType: DATETIME
value: '2026-05-01T08:30:00.000Z'
$from:
valueType: EMAIL
value:
- sales@acme.com
$to:
valueType: EMAIL
value:
- lead@example.com
$cc:
valueType: EMAIL
value: []
$bcc:
valueType: EMAIL
value: []
$privacySetting:
valueType: TEXT
value: null
$body:
valueType: HTML
value: <p>Hi there,</p><p>Following up on our chat earlier this week.</p>
relationships:
$account:
cardinality: has_many
objectType: account
values:
- acc_cm4stu901uvw234
$contact:
cardinality: has_many
objectType: contact
values:
- con_cm2ghi789jkl012
objectType: email
accessLevel: FULL
EmailListResponse:
type: object
properties:
object:
type: string
description: The object type, always `"list"`.
data:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the entity.
createdAt:
type: string
description: ISO 8601 timestamp of when the entity was created.
updatedAt:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp of when the entity was last updated, or null.
httpLink:
anyOf:
- type: string
- type: 'null'
description: URL to view the entity in the Lightfield web app, or null.
externalId:
anyOf:
- type: string
- type: 'null'
description: External identifier for the entity, or null if unset.
relationships:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
cardinality:
type: string
description: Whether the relationship is `has_one` or `has_many`.
objectType:
type: string
description: The type of the related object (e.g. `account`, `contact`).
values:
type: array
items:
type: string
description: IDs of the related entities.
required:
- cardinality
- objectType
- values
description: Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`).
fields:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
valueType:
enum:
- ADDRESS
- CHECKBOX
- CURRENCY
- DATETIME
- EMAIL
- FULL_NAME
- MARKDOWN
- MULTI_SELECT
- NUMBER
- SINGLE_SELECT
- SOCIAL_HANDLE
- TELEPHONE
- TEXT
- URL
- HTML
description: The data type of the field.
value:
anyOf:
- type: string
- type: integer
minimum: -9007199254740991
maximum: 9007199254740991
- type: number
- type: boolean
- type: 'null'
- type: array
items:
type: string
- $ref: '#/components/schemas/Address'
- $ref: '#/components/schemas/FullName'
description: The field value, or null if unset.
required:
- valueType
- value
description: Field map for this email. Does not include `$body`; retrieve the email by ID for message HTML.
objectType:
enum:
- email
description: Always `email`.
accessLevel:
enum:
- FULL
- METADATA
description: The caller's resolved access level for this email.
required:
- id
- createdAt
- updatedAt
- httpLink
- relationships
- fields
- objectType
- accessLevel
additionalProperties: false
description: Array of email objects for the current page.
totalCount:
type: integer
minimum: 0
maximum: 9007199254740991
description: Total number of entities matching the query.
required:
- object
- data
- totalCount
examples:
- object: list
data:
- id: eml_cm0abc456def789
createdAt: '2026-05-01T09:00:00.000Z'
updatedAt: '2026-05-01T10:00:00.000Z'
httpLink: null
fields:
$subject:
valueType: TEXT
value: Following up on our chat
$sentAt:
valueType: DATETIME
value: '2026-05-01T08:30:00.000Z'
$from:
valueType: EMAIL
value:
- sales@acme.com
$to:
valueType: EMAIL
value:
- lead@example.com
$cc:
valueType: EMAIL
value: []
$bcc:
valueType: EMAIL
value: []
$privacySetting:
valueType: TEXT
value: null
relationships:
$account:
cardinality: has_many
objectType: account
values:
- acc_cm4stu901uvw234
$contact:
cardinality: has_many
objectType: contact
values:
- con_cm2ghi789jkl012
objectType: email
accessLevel: FULL
- id: eml_cm1xyz123uvw456
createdAt: '2026-04-29T15:12:00.000Z'
updatedAt: '2026-04-29T15:12:00.000Z'
httpLink: null
fields:
$subject:
valueType: TEXT
value: null
$sentAt:
valueType: DATETIME
value: '2026-04-29T15:11:30.000Z'
$from:
valueType: EMAIL
value:
- ceo@acme.com
$to:
valueType: EMAIL
value:
- member@lightfield.com
$cc:
valueType: EMAIL
value: []
$bcc:
valueType: EMAIL
value: []
$privacySetting:
valueType: TEXT
value: null
relationships:
$account:
cardinality: has_many
objectType: account
values:
- acc_cm4stu901uvw234
objectType: email
accessLevel: METADATA
totalCount: 2
InternalServerError:
type: object
properties:
type:
const: internal_server_error
message:
type: string
default: Internal Server Error
required:
- type
- message
GatewayTimeoutError:
type: object
properties:
type:
const: gateway_timeout
message:
type: string
default: Gateway Timeout
required:
- type
- message
TooManyRequestsError:
type: object
properties:
type:
const: too_many_requests
message:
type: string
default: Too Many Requests
required:
- type
- message
UnsupportedMediaTypeError:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightfield/refs/heads/main/openapi/lightfield-emails-api-openapi.yml