Email Addresses

Email Addresses (also referred to as mailboxes) can be onboarded to Luella to be used for sending outreach messages to uploaded contacts. As of now, Luella supports Google and Custom SMTP/IMAP mailboxes. These onboarded mailboxes can be associated with clusters (for IP isolation) and profiles (for context personalization) to enable dedicated warmup and outreach strategies.

The email address model

The email address model captures mailbox credentials, provider type, association details, warmup settings, and metadata for sending logic and personalization.

Properties

Name
emailAddressId
Type
string
Description
Unique identifier for the email address resource.
Name
mailboxId
Type
string
Description
System identifier used internally to fetch mailbox metadata.
Name
provider
Type
string
Description
Either 'google' or 'custom' depending on the method used to onboard.
Name
warmupStatus
Type
string
Description
Current warmup state. One of 'Enabled' or 'Disabled'.
Name
persona
Type
string
Description
Optional persona or name associated with this mailbox.
Name
associatedClusterId
Type
string
Description
ID of the cluster the email address is associated with.
Name
associatedProfileId
Type
string
Description
ID of the profile associated for business context.
Name
dailyWarmupLimit
Type
number
Description
Maximum number of warmup emails to send per day.
Name
dailyWarmupIncrement
Type
number
Description
Daily increase in warmup volume.
Name
initialWarmupRate
Type
number
Description
Starting rate for warmup volume.
Name
warmupEnabledAt
Type
timestamp (ISO string)
Description
Timestamp when warmup was activated.
Name
signature
Type
string
Description
Email signature appended to all messages.
Name
createdAt
Type
timestamp (ISO string)
Description
Timestamp of when this email address was created.
Name
lastUpdatedAt
Type
timestamp (ISO string)
Description
Timestamp of when this record was last updated.

POST/email-addresses/ListEmailAddresses

List all email addresses

This endpoint retrieves all onboarded email addresses (mailboxes) under a workspace, with optional filters based on warmup status or association.

Required attributes

Name
userId
Type
string
Description
The user making the request.
Name
workspaceId
Type
string
Description
The workspace from which to list email addresses.

Optional attributes

Name
warmupStatus
Type
string
Description
Filter based on warmup status ('Enabled' or 'Disabled').
Name
associatedClusterId
Type
string
Description
Filter by cluster ID.
Name
associatedProfileId
Type
string
Description
Filter by profile ID.
Name
nextToken
Type
string
Description
Token for pagination.
Name
maxItems
Type
integer
Description
Limit number of results.

Request

POST

/email-addresses/ListEmailAddresses

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "warmupStatus": "Enabled",
  "maxItems": 10
}

Response

{
  "emailAddresses": [
    {
      "emailAddressId": "developer@luella.ai",
      "mailboxId": "mailbox_001",
      "provider": "google",
      "warmupStatus": "Enabled",
      "persona": "Sam Outreach",
      "associatedClusterId": "cluster_123",
      "associatedProfileId": "profile_456",
      "createdAt": "2024-11-01T12:00:00.000Z"
    }
  ],
  "nextToken": null
}

POST/email-addresses/CreateEmailAddress

Create a new email address

Onboard a new mailbox to Luella. You can connect a Google mailbox using an OAuth code, or a custom mailbox using SMTP/IMAP credentials.

Required attributes

Name
userId
Type
string
Description
User initiating the mailbox onboarding.
Name
workspaceId
Type
string
Description
Workspace to onboard this email address into.
Name
provider
Type
string
Description
One of 'google' or 'custom'.

Optional attributes

Name
emailAddressId
Type
string
Description
Optional unique email address identifier to register.
Name
persona
Type
string
Description
Friendly name associated with the mailbox.
Name
code
Type
string
Description
OAuth token code used for Google inboxes.
Name
customCredentials
Type
object
Description
Object containing SMTP/IMAP configuration for custom inboxes.

Request

POST

/email-addresses/CreateEmailAddress

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "provider": "custom",
  "emailAddressId": "bot@example.com",
  "persona": "Outreach Bot",
  "customCredentials": {
    "smtpHost": "smtp.example.com",
    "smtpUser": "bot@example.com",
    "smtpPassword": "password123",
    "smtpPort": 587,
    "imapHost": "imap.example.com",
    "imapUser": "bot@example.com",
    "imapPassword": "password123",
    "imapPort": 993
  }
}

Response

{
  "emailAddressId": "bot@example.com"
}

POST/email-addresses/GetEmailAddress

Get an email address

Retrieve metadata, warmup configuration, and associations for a specific mailbox using its internal mailbox ID.

Required attributes

Name
userId
Type
string
Description
Requesting user.
Name
workspaceId
Type
string
Description
Workspace that owns the mailbox.
Name
mailboxId
Type
string
Description
Identifier for the mailbox to retrieve.

Request

POST

/email-addresses/GetEmailAddress

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "mailboxId": "mailbox_001"
}

Response

{
  "emailAddressId": "developer@luella.ai",
  "mailboxId": "mailbox_001",
  "provider": "google",
  "warmupStatus": "Enabled",
  "associatedClusterId": "cluster_123",
  "associatedProfileId": "profile_456",
  "dailyWarmupLimit": 25,
  "dailyWarmupIncrement": 5,
  "initialWarmupRate": 10,
  "warmupEnabledAt": "2024-10-01T00:00:00.000Z",
  "persona": "John Outreach",
  "signature": "Best,
John",
  "createdAt": "2024-09-01T00:00:00.000Z",
  "lastUpdatedAt": "2024-10-15T12:34:00.000Z"
}

POST/email-addresses/UpdateEmailAddress

Update an email address

Update the settings or associations of an onboarded email address, including warmup configuration, persona, or signature.

Required attributes

Name
userId
Type
string
Description
User issuing the update.
Name
workspaceId
Type
string
Description
Workspace of the mailbox.
Name
emailAddressId
Type
string
Description
Unique ID of the email address being updated.
Name
warmupStatus
Type
string
Description
New warmup status (Enabled or Disabled).

Optional attributes

Name
provider
Type
string
Description
Optionally override provider.
Name
associatedClusterId
Type
string
Description
Updated cluster association.
Name
associatedProfileId
Type
string
Description
Updated profile association.
Name
dailyWarmupLimit
Type
number
Description
Daily warmup send cap.
Name
dailyWarmupIncrement
Type
number
Description
Daily increment for warmup volume.
Name
initialWarmupRate
Type
number
Description
Starting warmup volume.
Name
warmupEnabledAt
Type
timestamp (ISO string)
Description
Timestamp of when warmup was enabled.
Name
persona
Type
string
Description
Updated persona name.
Name
signature
Type
string
Description
Updated signature text.

Request

POST

/email-addresses/UpdateEmailAddress

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "emailAddressId": "developer@luella.ai",
  "warmupStatus": "Enabled",
  "associatedClusterId": "cluster_123",
  "associatedProfileId": "profile_456",
  "dailyWarmupLimit": 30,
  "dailyWarmupIncrement": 5,
  "initialWarmupRate": 10,
  "warmupEnabledAt": "2024-10-01T00:00:00.000Z",
  "persona": "Jane Outreach",
  "signature": "Thanks,
Jane"
}

Response

{
  "emailAddressId": "developer@luella.ai",
  "provider": "custom"
}

POST/email-addresses/AssociateEmailAddress

Associate an email address

Associate an onboarded email address to either a cluster (for IP warming) or a profile (for business context). One address can be associated with both.

Required attributes

Name
userId
Type
string
Description
ID of the user making the request.
Name
workspaceId
Type
string
Description
Workspace that owns the email address.
Name
resourceType
Type
'cluster' | 'profile'
Description
Type of association. One of 'cluster' or 'profile'.
Name
resourceId
Type
string
Description
ID of the cluster or profile to associate with.
Name
emailAddressId
Type
string
Description
Email address to be associated.

Request

POST

/email-addresses/AssociateEmailAddress

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "resourceType": "cluster",
  "resourceId": "cluster_123",
  "emailAddressId": "developer@luella.ai"
}

Response

{
  "emailAddressId": "developer@luella.ai",
  "resourceId": "cluster_123",
  "resourceType": "cluster"
}

POST/email-addresses/DisassociateEmailAddress

Disassociate an email address

Remove the association between an email address and a cluster or profile.

Required attributes

Name
userId
Type
string
Description
Requesting user ID.
Name
workspaceId
Type
string
Description
Workspace of the email address.
Name
emailAddressId
Type
string
Description
The email address being disassociated.
Name
resourceId
Type
string
Description
ID of the cluster or profile to remove.
Name
resourceType
Type
'cluster' | 'profile'
Description
One of 'cluster' or 'profile'.

Request

POST

/email-addresses/DisassociateEmailAddress

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "emailAddressId": "developer@luella.ai",
  "resourceId": "cluster_123",
  "resourceType": "cluster"
}

Response

{}

POST/email-addresses/DeleteEmailAddress

Delete an email address

Permanently deletes an onboarded email address and all associated data.

Required attributes

Name
userId
Type
string
Description
ID of the user making the request.
Name
workspaceId
Type
string
Description
Workspace from which the email address should be deleted.
Name
emailAddressId
Type
string
Description
Unique identifier of the email address to delete.

Request

POST

/email-addresses/DeleteEmailAddress

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "emailAddressId": "developer@luella.ai"
}

Response

{}