Contacts

Contacts in Luella are the prospects you want to send outreach emails to. They can also be labeled as "Leads". Contacts are only meaningful when associated to a campaign. Therefore, when using the API, a contact must first be created and then associated to a campaign that will do the actual outreach sending.

The contact model

This model represents a single lead or prospect, including company details, email provider, and mapped variable values.

Properties

Name
contactId
Type
string
Description
Unique identifier for the contact.
Name
workspaceId
Type
string
Description
Workspace the contact belongs to.
Name
emailAddressId
Type
string
Description
ID of the email address associated with this contact.
Name
emailProvider
Type
string
Description
Email provider of the contact (e.g. google, outlook, custom).
Name
status
Type
string[]
Description
Status tags applied to the contact.
Name
executionStatus
Type
string
Description
The current stage of campaign execution for this contact.
Name
contact
Type
string
Description
Name of the contact.
Name
company
Type
string
Description
Name of the company.
Name
website
Type
string
Description
Company website.
Name
phoneNumber
Type
string
Description
Phone number for the contact.
Name
variables
Type
object
Description
Object mapping variable IDs to custom values for this contact.
Name
createdAt
Type
timestamp (ISO string)
Description
Timestamp of contact creation.
Name
lastUpdatedAt
Type
timestamp (ISO string)
Description
Timestamp of last update to the contact.

POST/contacts/ListContacts

List all contacts

Retrieve a list of contacts. You can optionally filter by campaign (using resourceId), email provider, creation date range, and execution status.

Required attributes

Name
userId
Type
string
Description
ID of the user making the request.
Name
workspaceId
Type
string
Description
Workspace the contacts belong to.

Optional attributes

Name
emailProviders
Type
('google' | 'outlook' | 'custom')[]
Description
Filter contacts by provider (e.g. google, outlook).
Name
createdBeforeDate
Type
string
Description
Filter for contacts created before this date (YYYY-MM-DD).
Name
createdAfterDate
Type
string
Description
Filter for contacts created after this date (YYYY-MM-DD).
Name
resourceId
Type
string
Description
Campaign ID to filter contacts associated with that campaign.
Name
sortOrder
Type
string
Description
Optional sort direction.
Name
nextToken
Type
string
Description
Token for pagination.
Name
maxItems
Type
number
Description
Maximum number of results per page.

Request

POST

/contacts/ListContacts

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "resourceId": "camp_001",
  "maxItems": 10
}

Response

{
  "contacts": [
    {
      "contactId": "contact_001",
      "emailAddressId": "email_001",
      "emailProvider": "google",
      "status": ["Ongoing"],
      "executionStatus": "Pending",
      "contact": "John Doe",
      "company": "Acme Corp",
      "website": "https://acme.com",
      "phoneNumber": "+1-555-123-4567"
    }
  ],
  "nextToken": null
}

POST/contacts/CreateContact

Create a new contact

Create a new contact and associate it with an email address. To send outreach, the contact must also be associated with a campaign.

Required attributes

Name
userId
Type
string
Description
ID of the user creating the contact.
Name
workspaceId
Type
string
Description
Workspace the contact will belong to.
Name
emailAddressId
Type
string
Description
ID of the email address associated with this contact.

Optional attributes

Name
contact
Type
string
Description
Contact’s name.
Name
company
Type
string
Description
Company name.
Name
website
Type
string
Description
Company website.
Name
phoneNumber
Type
string
Description
Contact’s phone number.
Name
variableIdToValueMappings
Type
object
Description
A mapping of variableId to string values for this contact.

Request

POST

/contacts/CreateContact

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "emailAddressId": "email_001",
  "contact": "Jane Prospect",
  "company": "Startup Inc.",
  "website": "https://startup.com",
  "phoneNumber": "+1-123-456-7890",
  "variableIdToValueMappings": {
    "variable_001": "AI automation",
    "variable_002": "Product Manager"
  }
}

Response

{
  "contactId": "contact_002"
}

POST/contacts/GetContact

Get a contact

Retrieve all saved information about a contact, including email provider, variables, and company details.

Required attributes

Name
userId
Type
string
Description
ID of the user making the request.
Name
workspaceId
Type
string
Description
Workspace the contact belongs to.
Name
contactId
Type
string
Description
Unique identifier of the contact to retrieve.

Request

POST

/contacts/GetContact

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "contactId": "contact_001"
}

Response

{
  "workspaceId": "workspace_456",
  "contactId": "contact_001",
  "emailAddressId": "email_001",
  "emailProvider": "google",
  "status": ["lead"],
  "contact": "John Doe",
  "company": "Acme Corp",
  "website": "https://acme.com",
  "phoneNumber": "+1-555-123-4567",
  "variables": {
    "variable_001": "Outreach Automation",
    "variable_002": "CTO"
  },
  "createdAt": "2024-04-01T00:00:00.000Z",
  "lastUpdatedAt": "2024-04-01T08:30:00.000Z"
}

POST/contacts/AssociateContact

Associate a contact

Associate a contact with a campaign in order to include them in outreach.

Required attributes

Name
userId
Type
string
Description
ID of the user performing the association.
Name
workspaceId
Type
string
Description
Workspace of the contact and campaign.
Name
resourceId
Type
string
Description
Campaign ID to associate the contact with.
Name
contactId
Type
string
Description
ID of the contact to associate.

Request

POST

/contacts/AssociateContact

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "resourceId": "camp_001",
  "contactId": "contact_001"
}

Response

{
  "associationId": "assoc_001"
}

POST/contacts/DisassociateContact

Disassociate a contact

Remove a contact's association with a campaign, effectively excluding them from further outreach in that campaign.

Required attributes

Name
userId
Type
string
Description
ID of the user performing the disassociation.
Name
workspaceId
Type
string
Description
Workspace of the contact and campaign.
Name
resourceId
Type
string
Description
Campaign ID to disassociate the contact from.
Name
contactId
Type
string
Description
ID of the contact to disassociate.

Request

POST

/contacts/DisassociateContact

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "resourceId": "camp_001",
  "contactId": "contact_001"
}

Response

{}

POST/contacts/UpdateContact

Update a contact

Update the contact's information, including mapped variables. Fields not explicitly provided will be overwritten with null — make sure to resend values for fields you want to keep.

Required attributes

Name
userId
Type
string
Description
ID of the user updating the contact.
Name
workspaceId
Type
string
Description
Workspace of the contact.
Name
contactId
Type
string
Description
ID of the contact to update.
Name
emailAddressId
Type
string
Description
ID of the email address associated with this contact.

Optional attributes

Name
emailProvider
Type
string
Description
Email provider (e.g. google, outlook, custom).
Name
status
Type
string[]
Description
Updated status tags.
Name
contact
Type
string
Description
Updated contact name.
Name
company
Type
string
Description
Updated company name.
Name
website
Type
string
Description
Updated company website.
Name
phoneNumber
Type
string
Description
Updated phone number.
Name
variableIdToValueMappings
Type
object
Description
Updated variable-to-value map for personalization.

Request

POST

/contacts/UpdateContact

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "contactId": "contact_001",
  "emailAddressId": "email_001",
  "contact": "Updated Name",
  "company": "Updated Inc.",
  "website": "https://updated.com",
  "phoneNumber": "+1-999-999-9999",
  "status": ["engaged"],
  "variableIdToValueMappings": {
    "variable_001": "Cold outreach",
    "variable_002": "CMO"
  }
}

Response

{
  "contactId": "contact_001"
}

POST/contacts/DeleteContact

Delete a contact

Permanently remove a contact from your workspace.

Required attributes

Name
userId
Type
string
Description
ID of the user performing the deletion.
Name
workspaceId
Type
string
Description
Workspace the contact belongs to.
Name
contactId
Type
string
Description
ID of the contact to delete.

Request

POST

/contacts/DeleteContact

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "contactId": "contact_001"
}

Response

{}