cotera
Logo

Lemlist

Authentication Type: API Key Description: Manage email campaigns, enrich leads, and track engagement activities through Lemlist's sales engagement platform.

Beta Notice

This tool is currently in beta testing and not yet available for general use.

To get the Lemlist tool added to your Cotera workspace, please contact our support team at support.cotera.co.

Authentication

To authenticate, you'll need a Lemlist API Key. Learn how to create one in the Lemlist API documentation.

Activity

Get Activities

List activities across campaigns — email sent, opened, clicked, replied, LinkedIn actions, and more. Supports filtering by activity type, campaign, lead, date range, and pagination.

Operation Type: Query (Read)

Parameters:

  • type string (optional): Filter by activity type (e.g. emailsSent, emailsOpened, emailsClicked, emailsReplied, linkedinInviteAccepted). Must match exact spelling from Lemlist's ActivityType enum.
  • campaignId string (optional): Filter by campaign identifier.
  • leadId string (optional): Filter by lead identifier.
  • isFirst boolean (optional): When true, only return the first activity.
  • offset number (optional): Number of records to skip for pagination (defaults to 0). Increment by limit to page through results.
  • limit number (optional): Records per request (defaults to 100, maximum 100).
  • minDate string (optional): Only return activities with createdAt >= minDate. Accepts a Unix timestamp or ISO 8601 datetime.
  • maxDate string (optional): Only return activities with createdAt <= maxDate. Must be after minDate. Accepts a Unix timestamp or ISO 8601 datetime.

Returns:

  • activities array of objects: Activity records, each with fields like _id, type, leadId, campaignId, sequenceId, sequenceStep, createdAt, userId, userName, leadFirstName, leadLastName, leadEmail, leadCompanyName, contactId, teamId, and lead.

Example:

{
  "type": "emailsReplied",
  "campaignId": "cam_abc123",
  "minDate": "2024-01-01T00:00:00Z",
  "maxDate": "2024-03-31T23:59:59Z",
  "limit": 100,
  "offset": 0
}

Campaign

Create Campaign

Create a new email outreach campaign in Lemlist. Returns the campaign ID and sequence ID needed to add steps and leads.

Operation Type: Mutation (Write)

Parameters:

  • name string (required): The name of the campaign.
  • timezone string (optional): Timezone for the campaign schedule (e.g. "America/New_York"). Defaults to null.

Returns:

  • id string: The campaign ID.
  • sequenceId string: The sequence ID (use with Add Email Step / Add LinkedIn Step).
  • scheduleIds array of strings: List of schedule IDs.
  • name string: The campaign name.
  • state string: The current state of the campaign (e.g. "draft").

Example:

{
  "name": "Q1 Outbound — Enterprise",
  "timezone": "America/New_York"
}

Get Campaign

Retrieve details of a specific Lemlist campaign by its ID.

Operation Type: Query (Read)

Parameters:

  • campaignId string (required): The ID of the campaign to fetch.

Returns:

  • id string: The campaign ID.
  • name string: The campaign name.
  • status string: The current status (e.g. "draft", "running", "paused").
  • createdAt string: ISO 8601 timestamp of when the campaign was created.
  • sequenceId string (nullable): The sequence ID associated with the campaign.
  • hasError boolean: Whether the campaign has any errors.

Example:

{
  "campaignId": "cam_abc123"
}

Get Campaign Leads

List the leads in a Lemlist campaign, newest first. Optionally filter by state and cap the number returned.

Operation Type: Query (Read)

Parameters:

  • campaignId string (required): The ID of the campaign to list leads for.
  • state string (optional): Filter by lead state (e.g. scanned, contacted, interested, notInterested). Leave empty for all states.
  • limit number (optional): Maximum number of leads to return (default 100, max 500).

Returns:

  • leads array of objects: Campaign leads, newest first. Each lead includes its id, contactId, state, and other lead fields.

Example:

{
  "campaignId": "cam_abc123",
  "state": "interested",
  "limit": 50
}

Get Campaign Sequences

Fetch the sequences of a Lemlist campaign, including each sequence's steps (email/LinkedIn/conditional), delays, messages, and step IDs. Useful for finding a stepId to skip, or understanding a campaign's structure.

Operation Type: Query (Read)

Parameters:

  • campaignId string (required): The ID of the campaign to fetch sequences for.

Returns:

  • sequences array of objects: The campaign sequences. Each entry includes its id, steps (with type, delay, message, subject, conditions, etc.), and level.

Example:

{
  "campaignId": "cam_abc123"
}

Contact

Get Contact

Retrieve a contact from the Lemlist people directory by ID or email. Returns contact details, custom fields, unsubscribe status, and associated campaigns.

Operation Type: Query (Read)

Parameters:

  • idOrEmail string (required): The contact ID or email address to look up.

Returns:

  • id string: The contact ID.
  • fullName string (nullable): The contact's full name.
  • email string (nullable): The contact's email address.
  • fields object: Custom fields and metadata for the contact.
  • unsubscribed boolean: Whether the contact has unsubscribed.
  • campaigns array of objects: List of campaigns the contact is part of.

Example:

{
  "idOrEmail": "jane.doe@example.com"
}

Get Contact Messages

Retrieve the message conversation (inbox thread) for a contact by contact ID. Returns the messages exchanged plus pagination metadata. Optionally marks the conversation as read.

Operation Type: Query (Read)

Parameters:

  • contactId string (required): The unique identifier of the contact whose conversation should be retrieved.
  • userId string (optional): ID of the user viewing the conversation. Required when markAsRead is true.
  • limit number (optional): The maximum number of messages to return.
  • skip number (optional): Number of messages to skip for pagination (defaults to 0).
  • markAsRead boolean (optional): When true, marks the conversation as read. Requires userId to be set. Defaults to false.

Returns:

  • messages array of objects: Message objects in the conversation, each with _id, type, messageId, createdAt, sendUserId, sendUserName, sendUserEmail, leadEmail, contactId, message (HTML body), subject, and attachments.
  • pagination object: Pagination metadata (total, page, limit).

Example:

{
  "contactId": "con_abc123",
  "limit": 20,
  "skip": 0,
  "markAsRead": false
}

Upsert Contact

Create or update a contact in the Lemlist people directory. Matches on email or LinkedIn URL to decide whether to create or update.

Operation Type: Mutation (Write)

Parameters:

  • email string (optional): The contact's email address.
  • linkedinUrl string (optional): The contact's LinkedIn profile URL.
  • firstName string (optional): The contact's first name.
  • lastName string (optional): The contact's last name.
  • phone string (optional): The contact's phone number.
  • jobTitle string (optional): The contact's job title.
  • companyDomain string (optional): The contact's company domain.
  • companyId string (optional): The Lemlist company ID to associate this contact with.

Returns:

  • id string: The contact ID.
  • created boolean: Whether a new contact was created.
  • updated boolean: Whether an existing contact was updated.
  • email string (nullable): The contact's email address.
  • fullName string (nullable): The contact's full name.

Example:

{
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "jobTitle": "VP of Engineering",
  "companyDomain": "example.com"
}

Company

Upsert Company

Create or update a company in the Lemlist directory. Matches on domain to decide whether to create or update.

Operation Type: Mutation (Write)

Parameters:

  • name string (required): The company name.
  • domain string (required): The company domain (e.g. "acme.com").
  • linkedinUrl string (optional): The company's LinkedIn page URL.
  • industry string (optional): The company's industry.
  • location string (optional): The company's location.
  • size string (optional): The company size (e.g. "51-200").
  • description string (optional): A short description of the company.

Returns:

  • id string: The company ID.
  • created boolean: Whether a new company was created.
  • updated boolean: Whether an existing company was updated.
  • domain string (nullable): The company's domain.

Example:

{
  "name": "Acme Inc",
  "domain": "acme.com",
  "industry": "Software",
  "size": "51-200",
  "location": "San Francisco, CA"
}

Enrichment

Enrich

Enrich a person with additional data — find a verified email, find a phone number, enrich LinkedIn profile data, or verify an email. Returns an enrichment ID to poll for results (see Get Enrichment Result).

At least one action flag (findEmail, findPhone, linkedinEnrichment, or verifyEmail) must be true, otherwise the tool throws an error. You must also supply enough identity input for the requested action (e.g. a linkedinUrl for linkedinEnrichment, or firstName + lastName + companyDomain/companyName to find an email).

Operation Type: Query (Read)

Parameters:

  • email string (optional): The person's email address. Required with verifyEmail; also usable as input for other enrichments. Defaults to null.
  • linkedinUrl string (optional): The person's LinkedIn profile URL. On its own this is enough for linkedinEnrichment. Defaults to null.
  • firstName string (optional): The person's first name. Combine with lastName + companyDomain/companyName to find an email without a linkedinUrl. Defaults to null.
  • lastName string (optional): The person's last name. Defaults to null.
  • companyDomain string (optional): The person's company website domain (e.g. example.com). Defaults to null.
  • companyName string (optional): The person's company name (e.g. Acme Inc). An alternative to companyDomain for matching. Defaults to null.
  • jobTitle string (optional): The person's job title. Improves email-finding accuracy. Defaults to null.
  • webhookUrl string (optional): URL Lemlist will POST the enrichment result to when it completes, as an alternative or addition to polling. Defaults to null.
  • findEmail boolean (optional): Find a verified email address. Needs firstName + lastName + companyDomain/companyName (jobTitle improves accuracy). Defaults to false.
  • findPhone boolean (optional): Find a phone number. Defaults to false.
  • linkedinEnrichment boolean (optional): Run LinkedIn profile enrichment. Needs linkedinUrl, or firstName + lastName + companyDomain/companyName. Defaults to false.
  • verifyEmail boolean (optional): Verify an existing email address. Requires the email input. Defaults to false.

Returns:

  • enrichmentId string: The ID of the enrichment request. Use with Get Enrichment Result to poll for the enriched data.

Example:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "companyDomain": "example.com",
  "jobTitle": "VP of Engineering",
  "findEmail": true,
  "linkedinEnrichment": true
}

Get Enrichment Result

Fetch the result of a Lemlist enrichment by its ID. Enrichment is asynchronous: while processing, the tool returns inProgress: true with an empty data object (HTTP 202). Poll until inProgress is false and status is "done".

Operation Type: Query (Read)

Parameters:

  • enrichmentId string (required): The enrichment ID returned by the Enrich tool (e.g. enr_123).

Returns:

  • enrichmentId string: The enrichment ID.
  • status string: The enrichment status (e.g. "done", "inProgress").
  • inProgress boolean: true when the enrichment is still processing. Poll again until false.
  • input object: The input parameters the enrichment was requested with.
  • data object: The enriched results (e.g. email, phone, LinkedIn data). Empty until the enrichment is done.

Example:

{
  "enrichmentId": "enr_abc123"
}

Inbox

Get Inboxes

List the inboxes (conversation threads) for a Lemlist user. Returns inbox metadata including the associated contact, channels, and reply status, plus pagination.

Operation Type: Query (Read)

Parameters:

  • userId string (required): The ID of the user whose inboxes (conversations) should be listed.
  • page number (optional): The page number to retrieve. Defaults to null.
  • limit number (optional): The maximum number of inboxes to return. Defaults to null.

Returns:

  • inboxes array of objects: Inbox (conversation) objects, each with _id, opportunities, lastActivityAt, channels, teamId, contactId, users, createdAt, haveReplies, lastRepliedAt, lastRepliedChannel, and contact (with _id, fullName, email).
  • pagination object: Pagination metadata (total, page, limit).

Example:

{
  "userId": "usr_abc123",
  "page": 1,
  "limit": 50
}

Send LinkedIn Message

Send a LinkedIn message to a lead from a Lemlist team member's connected LinkedIn account.

Operation Type: Mutation (Write)

Parameters:

  • sendUserId string (required): The ID of the Lemlist team member (user) whose connected LinkedIn account will send the message.
  • leadId string (required): The ID of the lead the message is being sent to.
  • contactId string (required): The ID of the contact the message is being sent to.
  • message string (required): The LinkedIn message content to send.

Returns:

  • ok boolean: Whether the LinkedIn message was accepted for sending.

Example:

{
  "sendUserId": "usr_abc123",
  "leadId": "lea_def456",
  "contactId": "con_ghi789",
  "message": "Hi Jane, I came across your profile and wanted to connect. Would love to share how we help engineering leaders like you."
}

Lead

Create Lead

Add a new lead to a specific Lemlist campaign. Supports standard fields plus arbitrary custom variables (via customFields) that become {{merge_tags}} in your campaign templates.

Operation Type: Mutation (Write)

Parameters:

  • campaignId string (required): The ID of the campaign to add the lead to.
  • email string (required): The lead's email address.
  • firstName string (optional): The lead's first name.
  • lastName string (optional): The lead's last name.
  • companyName string (optional): The lead's company name.
  • jobTitle string (optional): The lead's job title.
  • linkedinUrl string (optional): The lead's LinkedIn profile URL.
  • phone string (optional): The lead's phone number.
  • icebreaker string (optional): A personalized icebreaker message, available as {{icebreaker}} in templates.
  • customFields object (optional): Arbitrary custom variables to set on the lead. Each key becomes a merge tag available in templates as {{key}} — e.g. {"ai_company_trigger": "...", "ai_risk_hypothesis": "..."}. Keys that collide with standard fields (email, firstName, companyName, etc.) are ignored. Defaults to null.
  • deduplicate boolean (optional): When true, Lemlist checks other campaigns for the email and will not insert the lead if it already exists anywhere. Defaults to false.

Returns:

  • id string: The lead ID.
  • campaignId string: The campaign ID.
  • campaignName string: The campaign name.
  • email string: The lead's email address.
  • firstName string (nullable): The lead's first name.
  • lastName string (nullable): The lead's last name.
  • isPaused boolean: Whether the lead is paused.

Example:

{
  "campaignId": "cam_abc123",
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyName": "Acme Inc",
  "jobTitle": "VP of Engineering",
  "customFields": {
    "ai_company_trigger": "Just raised Series B",
    "ai_risk_hypothesis": "Scaling engineering team rapidly"
  },
  "deduplicate": true
}

Get Lead

Look up a lead by email address across all campaigns. Returns lead status, campaign information, and custom variables.

Operation Type: Query (Read)

Parameters:

  • email string (required): The email address of the lead to look up.

Returns:

  • leads array of objects: Lead objects with id, status, state, isPaused, campaignId, campaignName, campaignStatus, and variables.

Example:

{
  "email": "jane.doe@example.com"
}

Launch Lead

Launch a lead that is in review (start sending them the campaign sequence). Requires an emailPro plan or higher. Fails if the lead is paused, already launched, or the campaign has step errors.

Operation Type: Mutation (Write)

Parameters:

  • leadId string (required): The ID of the lead to launch.

Returns:

  • ok boolean: Whether the lead was launched.

Example:

{
  "leadId": "lea_abc123"
}

Skip Step

Skip a specific sequence step for a lead in a Lemlist campaign, so that step is not sent to them. Condition steps cannot be skipped.

Operation Type: Mutation (Write)

Parameters:

  • campaignId string (required): The ID of the campaign the lead is in.
  • leadIdOrEmail string (required): The lead's ID or email address.
  • stepId string (required): The ID of the sequence step to skip for this lead. Use Get Campaign Sequences to find step IDs.

Returns:

  • skipped boolean: Whether the step was skipped for the lead.

Example:

{
  "campaignId": "cam_abc123",
  "leadIdOrEmail": "jane.doe@example.com",
  "stepId": "stp_def456"
}

Update Lead Variables

Set custom variable values on an existing Lemlist lead (by lead ID), creating any variables that do not exist yet. Use this to populate personalization merge tags like {{ai_company_trigger}} on a lead that already exists.

Operation Type: Mutation (Write)

Parameters:

  • leadId string (required): The Lemlist lead ID (e.g. "lea_8xJSc7sV7ggpiVnXe"), as returned by Create Lead or Get Lead.
  • variables object (required): Custom variables to set on the lead as key/value pairs. Each key is a merge tag available in templates as {{key}}. Keys that collide with standard fields (email, firstName, companyName, etc.) are ignored.

Returns:

  • leadId string: The lead ID that was updated.
  • ok boolean: true when the update succeeded.
  • updated array of strings: The variable names that were sent.

Example:

{
  "leadId": "lea_8xJSc7sV7ggpiVnXe",
  "variables": {
    "ai_company_trigger": "Just raised a $20M Series B",
    "ai_role_relevance": "Scaling their data infrastructure team"
  }
}

Sequence

Add Email Step

Add an email step to a Lemlist campaign sequence. Use the sequenceId returned from Create Campaign to attach a subject and message to the sequence.

Plain text is accepted and automatically converted to HTML paragraphs and <br /> tags so formatting is preserved. You may also pass HTML directly. Merge tags like {{firstName}} or {{ai_company_trigger}} work in either format.

Operation Type: Mutation (Write)

Parameters:

  • sequenceId string (required): The ID of the sequence to add the email step to (the sequenceId returned when creating a campaign).
  • subject string (required): The email subject line. Maximum 400 characters (applied to the raw template, including any Liquid syntax).
  • message string (required): The body content of the email. Plain text or HTML. Merge tags work in either case.
  • index number (optional): The position within the sequence to insert the step (must be >= -1). If omitted or greater than the number of existing steps, the step is added to the end.
  • delay number (optional): Delay in days before executing this step (0–1500). Defaults to 0 for the first step and 1 for subsequent steps.

Returns:

  • id string: The step ID.
  • type string: The step type (always "email").
  • delay number (nullable): The delay in days before executing the step.
  • emailTemplateId string (nullable): The ID of the email template created for this step.
  • message string (nullable): The body content of the email.

Example:

{
  "sequenceId": "seq_abc123",
  "subject": "Quick question about {{companyName}}'s growth",
  "message": "Hi {{firstName}},\n\nI noticed {{ai_company_trigger}}.\n\nWould love to share how we help teams like yours.\n\nBest,\nAlex",
  "delay": 0
}

Add LinkedIn Step

Add a LinkedIn step to a Lemlist campaign sequence — connection invite, message, profile visit, follow, like/comment on last post, or withdraw invitation. Use alongside Add Email Step to build mixed email + LinkedIn cadences.

Operation Type: Mutation (Write)

Parameters:

  • sequenceId string (required): The ID of the sequence to add the LinkedIn step to (the sequenceId returned when creating a campaign).
  • type string (required): The LinkedIn action. One of:
    • linkedinVisit — view the prospect's profile
    • linkedinInvite — send a connection request (optional note via message)
    • linkedinSend — send a direct message to a connection (message required)
    • linkedinFollow — follow the prospect
    • linkedinLikeLastPost — like the prospect's most recent post
    • linkedinCommentLastPost — comment on the prospect's most recent post
    • linkedinWithdrawInvitation — withdraw a pending connection request
  • message string (optional): The message text. Used by linkedinInvite (the connection note, optional — keep under ~300 chars) and linkedinSend (required). Plain text only. Merge tags like {{firstName}} work. Ignored by visit/follow/like/comment/withdraw steps. Defaults to null.
  • altMessage string (optional): Alternate message for linkedinSend steps only (Lemlist A/B testing). Defaults to null.
  • index number (optional): The position within the sequence to insert the step (must be >= -1). If omitted or greater than the number of existing steps, the step is added to the end. Defaults to null.
  • delay number (optional): Delay in days before executing this step (0–1500). Defaults to 0 for the first step and 1 for subsequent steps. Defaults to null.

Returns:

  • id string: The step ID.
  • type string: The step type that was created.
  • delay number (nullable): The delay in days before executing the step.
  • message string (nullable): The message stored on the step, if any.

Example:

{
  "sequenceId": "seq_abc123",
  "type": "linkedinInvite",
  "message": "Hi {{firstName}}, I came across your profile and thought it would be great to connect.",
  "delay": 2
}

Common Use Cases

Build a Full Outreach Sequence:

  • Create a campaign with Create Campaign to get the campaignId and sequenceId
  • Add email steps with Add Email Step using the sequenceId
  • Add LinkedIn touchpoints with Add LinkedIn Step for multi-channel cadences
  • Add leads with Create Lead, passing custom personalization variables via customFields

Enrich Prospects Before Adding Them:

  • Call Enrich with findEmail: true and name + company domain to discover email addresses
  • Poll Get Enrichment Result until inProgress: false and status: "done"
  • Use the enriched data to populate Create Lead or Upsert Contact

Monitor Campaign Performance:

  • Use Get Campaign to check status and error state of a campaign
  • Use Get Campaign Leads to see leads filtered by state (interested, notInterested, etc.)
  • Use Get Activities to pull engagement events (opens, clicks, replies) by campaign or date range

Manage Replies and Conversations:

  • Use Get Inboxes to list conversation threads for a team member
  • Use Get Contact Messages to read the full message thread for a specific contact
  • Use Send LinkedIn Message to respond to a lead via LinkedIn from within Cotera

Personalize Existing Leads:

  • Look up a lead with Get Lead to confirm they exist before re-enrolling
  • Set or update merge tag values with Update Lead Variables without re-creating the lead
  • Use Skip Step to bypass a sequence step that's no longer relevant for a specific lead