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 `client.Email.List(ctx, query) (*EmailListResponse, error)` **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 - `query EmailListParams` - `Limit param.Field[int64]` Maximum number of records to return. Defaults to 25, maximum 25. - `Offset param.Field[int64]` Number of records to skip for pagination. Defaults to 0. ### Returns - `type EmailListResponse struct{…}` - `Data []EmailListResponseData` Array of email objects for the current page. - `ID string` Unique identifier for the entity. - `AccessLevel string` The caller's resolved access level for this email. - `const EmailListResponseDataAccessLevelFull EmailListResponseDataAccessLevel = "FULL"` - `const EmailListResponseDataAccessLevelMetadata EmailListResponseDataAccessLevel = "METADATA"` - `CreatedAt string` ISO 8601 timestamp of when the entity was created. - `Fields map[string, EmailListResponseDataField]` Field map for this email. Does not include `$body`; retrieve the email by ID for message HTML. - `Value EmailListResponseDataFieldValueUnion` The field value, or null if unset. - `string` - `float64` - `bool` - `type EmailListResponseDataFieldValueArray []string` - `type EmailListResponseDataFieldValueAddress struct{…}` - `City string` City name. - `Country string` 2-letter ISO 3166-1 alpha-2 country code. - `Latitude float64` Latitude coordinate. - `Longitude float64` Longitude coordinate. - `PostalCode string` Postal or ZIP code. - `State string` State or province. - `Street string` Street address line 1. - `Street2 string` Street address line 2. - `type EmailListResponseDataFieldValueFullName struct{…}` - `FirstName string` The contact's first name. - `LastName string` The contact's last name. - `ValueType string` The data type of the field. - `const EmailListResponseDataFieldValueTypeAddress EmailListResponseDataFieldValueType = "ADDRESS"` - `const EmailListResponseDataFieldValueTypeCheckbox EmailListResponseDataFieldValueType = "CHECKBOX"` - `const EmailListResponseDataFieldValueTypeCurrency EmailListResponseDataFieldValueType = "CURRENCY"` - `const EmailListResponseDataFieldValueTypeDatetime EmailListResponseDataFieldValueType = "DATETIME"` - `const EmailListResponseDataFieldValueTypeEmail EmailListResponseDataFieldValueType = "EMAIL"` - `const EmailListResponseDataFieldValueTypeFullName EmailListResponseDataFieldValueType = "FULL_NAME"` - `const EmailListResponseDataFieldValueTypeMarkdown EmailListResponseDataFieldValueType = "MARKDOWN"` - `const EmailListResponseDataFieldValueTypeMultiSelect EmailListResponseDataFieldValueType = "MULTI_SELECT"` - `const EmailListResponseDataFieldValueTypeNumber EmailListResponseDataFieldValueType = "NUMBER"` - `const EmailListResponseDataFieldValueTypeSingleSelect EmailListResponseDataFieldValueType = "SINGLE_SELECT"` - `const EmailListResponseDataFieldValueTypeSocialHandle EmailListResponseDataFieldValueType = "SOCIAL_HANDLE"` - `const EmailListResponseDataFieldValueTypeTelephone EmailListResponseDataFieldValueType = "TELEPHONE"` - `const EmailListResponseDataFieldValueTypeText EmailListResponseDataFieldValueType = "TEXT"` - `const EmailListResponseDataFieldValueTypeURL EmailListResponseDataFieldValueType = "URL"` - `const EmailListResponseDataFieldValueTypeHTML EmailListResponseDataFieldValueType = "HTML"` - `HTTPLink string` URL to view the entity in the Lightfield web app, or null. - `ObjectType string` Always `email`. - `const EmailListResponseDataObjectTypeEmail EmailListResponseDataObjectType = "email"` - `Relationships map[string, EmailListResponseDataRelationship]` 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 []string` IDs of the related entities. - `UpdatedAt string` ISO 8601 timestamp of when the entity was last updated, or null. - `ExternalID string` External identifier for the entity, or null if unset. - `Object string` The object type, always `"list"`. - `TotalCount int64` Total number of entities matching the query. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) emailListResponse, err := client.Email.List(context.TODO(), githubcomlightfldlightfieldgo.EmailListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", emailListResponse.Data) } ``` #### 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 `client.Email.Send(ctx, body) (*EmailSendResponse, error)` **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 - `body EmailSendParams` - `From param.Field[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. - `MessageBody param.Field[EmailSendParamsMessageBody]` Email message body (HTML or plain text). - `Content string` Email body content. - `ContentType string` Defaults to `HTML`. - `const EmailSendParamsMessageBodyContentTypeHTML EmailSendParamsMessageBodyContentType = "HTML"` - `const EmailSendParamsMessageBodyContentTypeText EmailSendParamsMessageBodyContentType = "TEXT"` - `Subject param.Field[string]` Email subject. Cannot be empty. - `To param.Field[[]string]` Recipient email addresses (bare, no display names). At least 1, at most 500. - `Attachments param.Field[[]string]` Optional list of file IDs (uploaded via the Files API) to attach to the email. Maximum 5 attachments per email, each ≤ 3MB. - `Bcc param.Field[[]string]` Bcc recipients (same shape as `to`). - `Cc param.Field[[]string]` Cc recipients (same shape as `to`). ### Returns - `type EmailSendResponse struct{…}` - `SentAt string` ISO 8601 timestamp of when the send completed. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) emailSendResponse, err := client.Email.Send(context.TODO(), githubcomlightfldlightfieldgo.EmailSendParams{ From: "sales@acme.com", MessageBody: githubcomlightfldlightfieldgo.EmailSendParamsMessageBody{ Content: "Hi there,
Following up on our chat earlier this week.
", }, Subject: "Following up on our chat", To: []string{"lead@example.com"}, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", emailSendResponse.SentAt) } ``` #### Response ```json { "sentAt": "sentAt" } ``` ## Create a draft email `client.Email.Draft(ctx, body) (*EmailDraftResponse, error)` **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 - `body EmailDraftParams` - `From param.Field[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. - `Attachments param.Field[[]string]` Optional list of file IDs (uploaded via the Files API) to attach to the draft. Maximum 5 attachments per draft, each ≤ 3MB. - `Bcc param.Field[[]string]` Bcc recipients (same shape as `to`). - `Cc param.Field[[]string]` Cc recipients (same shape as `to`). - `MessageBody param.Field[EmailDraftParamsMessageBody]` Email message body (HTML or plain text). - `Content string` Email body content. - `ContentType string` Defaults to `HTML`. - `const EmailDraftParamsMessageBodyContentTypeHTML EmailDraftParamsMessageBodyContentType = "HTML"` - `const EmailDraftParamsMessageBodyContentTypeText EmailDraftParamsMessageBodyContentType = "TEXT"` - `Subject param.Field[string]` Email subject. - `To param.Field[[]string]` Recipient email addresses (bare, no display names). Up to 500. ### Returns - `type EmailDraftResponse struct{…}` - `DraftedAt string` ISO 8601 timestamp of when the draft was created. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) emailDraftResponse, err := client.Email.Draft(context.TODO(), githubcomlightfldlightfieldgo.EmailDraftParams{ From: "sales@acme.com", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", emailDraftResponse.DraftedAt) } ``` #### Response ```json { "draftedAt": "draftedAt" } ``` ## Domain Types ### Email Draft Response - `type EmailDraftResponse struct{…}` - `DraftedAt string` ISO 8601 timestamp of when the draft was created. ### Email List Response - `type EmailListResponse struct{…}` - `Data []EmailListResponseData` Array of email objects for the current page. - `ID string` Unique identifier for the entity. - `AccessLevel string` The caller's resolved access level for this email. - `const EmailListResponseDataAccessLevelFull EmailListResponseDataAccessLevel = "FULL"` - `const EmailListResponseDataAccessLevelMetadata EmailListResponseDataAccessLevel = "METADATA"` - `CreatedAt string` ISO 8601 timestamp of when the entity was created. - `Fields map[string, EmailListResponseDataField]` Field map for this email. Does not include `$body`; retrieve the email by ID for message HTML. - `Value EmailListResponseDataFieldValueUnion` The field value, or null if unset. - `string` - `float64` - `bool` - `type EmailListResponseDataFieldValueArray []string` - `type EmailListResponseDataFieldValueAddress struct{…}` - `City string` City name. - `Country string` 2-letter ISO 3166-1 alpha-2 country code. - `Latitude float64` Latitude coordinate. - `Longitude float64` Longitude coordinate. - `PostalCode string` Postal or ZIP code. - `State string` State or province. - `Street string` Street address line 1. - `Street2 string` Street address line 2. - `type EmailListResponseDataFieldValueFullName struct{…}` - `FirstName string` The contact's first name. - `LastName string` The contact's last name. - `ValueType string` The data type of the field. - `const EmailListResponseDataFieldValueTypeAddress EmailListResponseDataFieldValueType = "ADDRESS"` - `const EmailListResponseDataFieldValueTypeCheckbox EmailListResponseDataFieldValueType = "CHECKBOX"` - `const EmailListResponseDataFieldValueTypeCurrency EmailListResponseDataFieldValueType = "CURRENCY"` - `const EmailListResponseDataFieldValueTypeDatetime EmailListResponseDataFieldValueType = "DATETIME"` - `const EmailListResponseDataFieldValueTypeEmail EmailListResponseDataFieldValueType = "EMAIL"` - `const EmailListResponseDataFieldValueTypeFullName EmailListResponseDataFieldValueType = "FULL_NAME"` - `const EmailListResponseDataFieldValueTypeMarkdown EmailListResponseDataFieldValueType = "MARKDOWN"` - `const EmailListResponseDataFieldValueTypeMultiSelect EmailListResponseDataFieldValueType = "MULTI_SELECT"` - `const EmailListResponseDataFieldValueTypeNumber EmailListResponseDataFieldValueType = "NUMBER"` - `const EmailListResponseDataFieldValueTypeSingleSelect EmailListResponseDataFieldValueType = "SINGLE_SELECT"` - `const EmailListResponseDataFieldValueTypeSocialHandle EmailListResponseDataFieldValueType = "SOCIAL_HANDLE"` - `const EmailListResponseDataFieldValueTypeTelephone EmailListResponseDataFieldValueType = "TELEPHONE"` - `const EmailListResponseDataFieldValueTypeText EmailListResponseDataFieldValueType = "TEXT"` - `const EmailListResponseDataFieldValueTypeURL EmailListResponseDataFieldValueType = "URL"` - `const EmailListResponseDataFieldValueTypeHTML EmailListResponseDataFieldValueType = "HTML"` - `HTTPLink string` URL to view the entity in the Lightfield web app, or null. - `ObjectType string` Always `email`. - `const EmailListResponseDataObjectTypeEmail EmailListResponseDataObjectType = "email"` - `Relationships map[string, EmailListResponseDataRelationship]` 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 []string` IDs of the related entities. - `UpdatedAt string` ISO 8601 timestamp of when the entity was last updated, or null. - `ExternalID string` External identifier for the entity, or null if unset. - `Object string` The object type, always `"list"`. - `TotalCount int64` Total number of entities matching the query. ### Email Retrieve Response - `type EmailRetrieveResponse struct{…}` - `ID string` Unique identifier for the entity. - `AccessLevel EmailRetrieveResponseAccessLevel` The caller's resolved access level for this email. - `const EmailRetrieveResponseAccessLevelFull EmailRetrieveResponseAccessLevel = "FULL"` - `const EmailRetrieveResponseAccessLevelMetadata EmailRetrieveResponseAccessLevel = "METADATA"` - `CreatedAt string` ISO 8601 timestamp of when the entity was created. - `Fields map[string, EmailRetrieveResponseField]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `Value EmailRetrieveResponseFieldValueUnion` The field value, or null if unset. - `string` - `float64` - `bool` - `type EmailRetrieveResponseFieldValueArray []string` - `type EmailRetrieveResponseFieldValueAddress struct{…}` - `City string` City name. - `Country string` 2-letter ISO 3166-1 alpha-2 country code. - `Latitude float64` Latitude coordinate. - `Longitude float64` Longitude coordinate. - `PostalCode string` Postal or ZIP code. - `State string` State or province. - `Street string` Street address line 1. - `Street2 string` Street address line 2. - `type EmailRetrieveResponseFieldValueFullName struct{…}` - `FirstName string` The contact's first name. - `LastName string` The contact's last name. - `ValueType string` The data type of the field. - `const EmailRetrieveResponseFieldValueTypeAddress EmailRetrieveResponseFieldValueType = "ADDRESS"` - `const EmailRetrieveResponseFieldValueTypeCheckbox EmailRetrieveResponseFieldValueType = "CHECKBOX"` - `const EmailRetrieveResponseFieldValueTypeCurrency EmailRetrieveResponseFieldValueType = "CURRENCY"` - `const EmailRetrieveResponseFieldValueTypeDatetime EmailRetrieveResponseFieldValueType = "DATETIME"` - `const EmailRetrieveResponseFieldValueTypeEmail EmailRetrieveResponseFieldValueType = "EMAIL"` - `const EmailRetrieveResponseFieldValueTypeFullName EmailRetrieveResponseFieldValueType = "FULL_NAME"` - `const EmailRetrieveResponseFieldValueTypeMarkdown EmailRetrieveResponseFieldValueType = "MARKDOWN"` - `const EmailRetrieveResponseFieldValueTypeMultiSelect EmailRetrieveResponseFieldValueType = "MULTI_SELECT"` - `const EmailRetrieveResponseFieldValueTypeNumber EmailRetrieveResponseFieldValueType = "NUMBER"` - `const EmailRetrieveResponseFieldValueTypeSingleSelect EmailRetrieveResponseFieldValueType = "SINGLE_SELECT"` - `const EmailRetrieveResponseFieldValueTypeSocialHandle EmailRetrieveResponseFieldValueType = "SOCIAL_HANDLE"` - `const EmailRetrieveResponseFieldValueTypeTelephone EmailRetrieveResponseFieldValueType = "TELEPHONE"` - `const EmailRetrieveResponseFieldValueTypeText EmailRetrieveResponseFieldValueType = "TEXT"` - `const EmailRetrieveResponseFieldValueTypeURL EmailRetrieveResponseFieldValueType = "URL"` - `const EmailRetrieveResponseFieldValueTypeHTML EmailRetrieveResponseFieldValueType = "HTML"` - `HTTPLink string` URL to view the entity in the Lightfield web app, or null. - `ObjectType EmailRetrieveResponseObjectType` Always `email`. - `const EmailRetrieveResponseObjectTypeEmail EmailRetrieveResponseObjectType = "email"` - `Relationships map[string, EmailRetrieveResponseRelationship]` 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 []string` IDs of the related entities. - `UpdatedAt string` ISO 8601 timestamp of when the entity was last updated, or null. - `ExternalID string` External identifier for the entity, or null if unset. ### Email Send Response - `type EmailSendResponse struct{…}` - `SentAt string` ISO 8601 timestamp of when the send completed.