The Emails & Activities app (E&A) is a useful tool that enables monday.com CRM customers to manage client communication in one centralized location. Each contact is logged and tracked in the app's timeline for easy access to important details and updates.

Queries

You can use the timeline_item query to retrieve timeline data via the API.

Returns an array containing metadata about newly created items in the E&A timeline
Can only be queried directly at the root; can't be nested within another query

query {
  timeline_item(
    id: 1234567890
	) {
    board {
      id
    }
    item {
      name
    }
    id
    user {
      id
      name
    }
    title
    type
    content
    created_at
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `query ($timelineId: ID!) { timeline_item (id: $timelineId) { title type content created_at } }`;
const variables = {
  timelineId: 1234567890,
};
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following argument to reduce the number of results returned in your timeline_item query.

Argument	Description
id `ID!`	The unique identifier of the timeline item to return.

Fields

You can use the following fields to specify what information your timeline_item query will return.

Field	Description
board `Board`	The board on which the timeline item is located.
content `String`	The timeline item's content.
created_at `Date!`	The timeline item's creation date.
custom_activity_id `String`	The unique identifier of the timeline item's custom activity.
id `ID`	The timeline item's unique identifier.
item `Item`	The item that the timeline item is on.
title `String`	The title of the timeline item.
type `String`	The type of timeline item. Always returns `"activity"`.
user `User`	The user who created the timeline item.

Mutations

The API allows you to create and delete timeline items using the following mutations.

Create timeline item

The create_timeline_item mutation creates a new timeline item in the E&A app via the API. You can specify which fields to return in the mutation response.

Please note that currently, this is the only way to retrieve a timeline item's ID. It is not possible to retrieve it from the UI.

🚧
Timeline items created via the API won't trigger automations that run when a new E&A timeline item is created.

mutation {
	create_timeline_item (
    item_id: 9876543210,
    custom_activity_id: "8ca12626-7aeb-3ca7-7z1a-8ebdda488cd2",
    title: "Migrated Email",
    summary: "internal company email",
    content: "From: [email protected] <br> To: [email protected] [Asi Monday], [email protected] [Yoni Monday] <br> Subject: Deploy our first alpha version <br><br>Hey guys, <br>We are ready to deploy our first alpha version and enable<br>our clients to migrate into E&A!<br><br>Best regards,<br> Saar",
    timestamp: "2024-06-06T18:00:30Z",
    time_range: {
     start_timestamp: "2024-05-06T18:00:30Z", 
     end_timestamp: "2024-05-06T19:00:30Z"
    }
 ) {
  id
 }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `mutation ($item_id: ID!, $custom_activity_id: String!, $title: String!, $summary: String!, $timestamp: ISO8601DateTime!, $time_range: TimelineItemTimeRange!, $content: String!) { create_timeline_item (item_id: $item_id, custom_activity_id: $custom_activity_id, title: $title, summary: $summary, content: $content, time_range: $time_range, timestamp: $timestamp ) {
  id
 }
}`;
const variables = {
  item_id: 9876543210,
  custom_activity_id: "8ca12626-7aeb-3ca7-7z1a-8ebdda488cd2",
  title: "Migrated Email",
  summary: "internal company email",
  content: "From: [email protected] <br> To: [email protected] [Asi Monday], [email protected] [Yoni Monday] <br> Subject: Deploy our first alpha version <br><br>Hey guys, <br>We are ready to deploy our first alpha version and enable<br>our clients to migrate into E&A!<br><br>Best regards,<br> Saar",
	timestamp: "2024-06-06T18:00:30Z",
  time_range: {
    start_timestamp: "2024-05-06T18:00:30Z", 
    end_timestamp: "2024-05-06T19:00:30Z"
   }
};
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following arguments to define the new timeline item's characteristics.

Argument	Description	Supported Fields
content `String`	The new timeline item's content.
custom_activity_id `String!`	The ID of the new timeline item's custom activity.
item_id `ID!`	The ID of the item to create the new timeline item on.
location `String`	The location to add to the new timeline item. This input isn't verified as a location.
phone `String`	The phone number to add to the new timeline item. This input isn't verified as a phone number.
summary `String`	The new timeline item's summary. The maximum is 255 characters.
timestamp `ISO8601DateTime!`	The new timeline item's creation time.
time_range `TimelineItemTimeRange`	The start and end time of the new timeline item.	end_timestamp `ISO8601DateTime!` start_timestamp `ISO8601DateTime!`
title `String!`	The new timeline item's title.
url `String`	The URL to add to the new timeline item.

Delete timeline item

The delete_timeline_item mutation deletes a timeline item in the E&A app via the API. You can specify which fields to return in the mutation response.

mutation {
  delete_timeline_item (id: "1234567890") {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `mutation ($timelineId: String!) {
  delete_timeline_item (id: $timelineId) {
    id
  }
}`;
const variables = {
  timelineId: "1234567890",
};
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following argument to define which timeline item to delete.

Argument	Description
id `String!`	The unique identifier of the timeline item to delete.

Error Handling

Refer to the API error handling for a list of common error types, retry strategies, and troubleshooting examples.

When calling timeline_item, create_timeline_item, or delete_timeline_item, you may occasionally see standard GraphQL or HTTP errors. Here are the most common categories to check:

Error Type	Description	Next Steps
Permission or collaborator error	The caller doesn’t have access to the Emails & Activities app or the board/item.	Use a token tied to an account with access to the E&A app and the relevant board/item.
Validation error	The query or mutation contains invalid arguments, missing fields, or is nested incorrectly.	Ensure required arguments (like `id`, `item_id`, `custom_activity_id`) are present and properly formatted. Keep `summary` ≤ 255 chars.
Not found	The specified timeline item or item ID doesn’t exist or isn’t visible.	Confirm the IDs are correct and that the timeline item exists on the target item.
Rate-limit error	Too many requests in a short period.	Wait and retry after the duration specified in the Retry-After header (if provided).
Server or network error	Temporary outage or connectivity issue.	Retry with backoff; if it persists, contact monday.com support with the `request_id`.