> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Unipile: List Emails

> List emails from a connected Gmail/Google, Microsoft/Outlook, or IMAP mailbox, with folder, sender, date, and pagination filters.

List emails from a connected Gmail/Google, Microsoft/Outlook, or IMAP mailbox, with folder, sender, date, and pagination filters.

> [!NOTE]
>
> Tool ID: `unipile_list_emails`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'unipile_list_emails',
  {
    "account_id": "123456789"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute unipile_list_emails --input '{
  "account_id": "123456789"
}' --json
```

## Example response

The static output schema lacks the details for a reliable example. Use `deepline describe unipile_list_emails --json` for the complete live contract.

## Input reference

Returns a list of emails.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.message_id` | `string` | No | — | A filter to target items by message\_id. |
| `payload.thread_id` | `string` | No | — | A filter to target items by thread identifier. |
| `payload.meta_only` | `boolean` | No | — | Speed up the response by only returning the email metadata, excluding the body and attachments metadata. |
| `payload.include_headers` | `boolean` | No | — | Include the email headers in the response. `meta_only` must be false. |
| `payload.cursor` | `string` | No | — | A cursor for pagination purposes. To get the next page of entries, you need to make a new request and fulfill this field with the cursor received in the preceding request. This process should be repeated until all entries have been retrieved. Minimum length: 1. |
| `payload.before` | `string` | No | — | A filter to target items created before the datetime (exclusive). Must be an ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). Pattern: `^[1-2]\d{3}-[0-1]\d-[0-3]\dT\d{2}:\d{2}:\d{2}.\d{3}Z$`. |
| `payload.after` | `string` | No | — | A filter to target items created after the datetime (exclusive). Must be an ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). Pattern: `^[1-2]\d{3}-[0-1]\d-[0-3]\dT\d{2}:\d{2}:\d{2}.\d{3}Z$`. |
| `payload.limit` | `integer` | No | — | A limit for the number of items returned in the response. The value can be set between 1 and 250. Minimum: 1. Maximum: 250. |
| `payload.search` | `string` | No | — | Free-text search applied to subject and body at the same time. Microsoft: requests combining search with from, to, any\_email, before, after, thread\_id, message\_id or exclude\_folders are rejected with invalid\_request. IMAP: can be slow, only available within one folder, specified with folder or role, before and after are evaluated at day granularity, support depends on the IMAP server. IMAP requests combining search with any\_email, exclude\_folders, thread\_id, multiple from values or multiple to See the live schema for the complete constraint. |
| `payload.any_email` | `string` | No | — | A filter to target items sent to or received from a comma-separated list of email addresses. |
| `payload.to` | `string` | No | — | A filter to target items related to a certain recipient, either in the to, cc or bcc field. |
| `payload.from` | `string` | No | — | A filter to target items related to a certain sender. |
| `payload.exclude_folders` | `string` | No | — | A filter to exclude items from a comma-separated list of folder provider\_id ( ignored if folder parameter is used ). |
| `payload.folder` | `string` | No | — | A filter to target items related to a certain folder provider\_id. |
| `payload.account_id` | `string` | Yes | — | A filter to target items related to a certain account. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Returns a list of emails.",
    "properties": {
      "message_id": {
        "type": "string",
        "description": "A filter to target items by message_id."
      },
      "thread_id": {
        "type": "string",
        "description": "A filter to target items by thread identifier."
      },
      "meta_only": {
        "type": "boolean",
        "description": "Speed up the response by only returning the email metadata, excluding the body and attachments metadata."
      },
      "include_headers": {
        "type": "boolean",
        "description": "Include the email headers in the response. `meta_only` must be false."
      },
      "cursor": {
        "type": "string",
        "description": "A cursor for pagination purposes. To get the next page of entries, you need to make a new request and fulfill this field with the cursor received in the preceding request. This process should be repeated until all entries have been retrieved.",
        "minLength": 1
      },
      "before": {
        "type": "string",
        "description": "A filter to target items created before the datetime (exclusive). Must be an ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).",
        "pattern": "^[1-2]\\d{3}-[0-1]\\d-[0-3]\\dT\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
      },
      "after": {
        "type": "string",
        "description": "A filter to target items created after the datetime (exclusive). Must be an ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).",
        "pattern": "^[1-2]\\d{3}-[0-1]\\d-[0-3]\\dT\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
      },
      "limit": {
        "type": "integer",
        "description": "A limit for the number of items returned in the response. The value can be set between 1 and 250.",
        "minimum": 1,
        "maximum": 250
      },
      "search": {
        "type": "string",
        "description": "Free-text search applied to subject and body at the same time. Microsoft: requests combining search with from, to, any_email, before, after, thread_id, message_id or exclude_folders are rejected with invalid_request. IMAP: can be slow, only available within one folder, specified with folder or role, before and after are evaluated at day granularity, support depends on the IMAP server. IMAP requests combining search with any_email, exclude_folders, thread_id, multiple from values or multiple to values are rejected with invalid_request."
      },
      "any_email": {
        "type": "string",
        "description": "A filter to target items sent to or received from a comma-separated list of email addresses."
      },
      "to": {
        "type": "string",
        "description": "A filter to target items related to a certain recipient, either in the to, cc or bcc field."
      },
      "from": {
        "type": "string",
        "description": "A filter to target items related to a certain sender."
      },
      "exclude_folders": {
        "type": "string",
        "description": "A filter to exclude items from a comma-separated list of folder provider_id ( ignored if folder parameter is used )."
      },
      "folder": {
        "type": "string",
        "description": "A filter to target items related to a certain folder provider_id."
      },
      "account_id": {
        "type": "string",
        "description": "A filter to target items related to a certain account."
      }
    },
    "required": [
      "account_id"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | @todo List of Emails. |
| `result.data.object` | `"EmailList"` | Yes | — | Allowed: `EmailList`. |
| `result.data.items` | `array` | Yes | — | — |
| `result.data.items[].object` | `"Email"` | Yes | — | — |
| `result.data.items[].id` | `string` | Yes | — | A unique identifier. |
| `result.data.items[].deprecated_id` | `string` | Yes | — | A unique identifier. |
| `result.data.items[].kind` | `"0_ref"` | Yes | — | — |
| `result.data.items[].account_id` | `string` | Yes | — | A unique identifier. |
| `result.data.items[].type` | `"MAIL" \| "GOOGLE" \| "ICLOUD" \| "OUTLOOK" \| "EXCHANGE" \| "GOOGLE_OAUTH"` | Yes | — | — |
| `result.data.items[].date` | `unknown` | Yes | — | An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect. |
| `result.data.items[].role` | `"inbox" \| "sent" \| "archive" \| "drafts" \| "trash" \| "spam" \| "all" \| "important" \| "starred" \| "unknown"` | Yes | — | — |
| `result.data.items[].folders` | `array` | Yes | — | — |
| `result.data.items[].folderIds` | `array` | Yes | — | — |
| `result.data.items[].read_date` | `unknown \| null` | No | — | — |
| `result.data.items[].message_id` | `string` | Yes | — | — |
| `result.data.items[].provider_id` | `string` | Yes | — | — |
| `result.data.items[].body_plain` | `""` | Yes | — | — |
| `result.data.items[].body` | `""` | Yes | — | — |
| `result.data.items[].from_attendee` | `object` | Yes | — | — |
| `result.data.items[].from_attendee.display_name` | `string` | No | — | — |
| `result.data.items[].from_attendee.profile_picture` | `string` | No | — | — |
| `result.data.items[].from_attendee.identifier` | `string` | Yes | — | — |
| `result.data.items[].from_attendee.identifier_type` | `"CHAT_ATTENDEE_ID" \| "PHONE_NUMBER" \| "EMAIL_ADDRESS" \| "MESSENGER_ID" \| "MESSENGER_THREAD_ID" \| "TIKTOK_ID" \| "TIKTOK_THREAD_ID" \| "TWITTER_ID" \| "TWITTER_THREAD_ID" \| "INSTAGRAM_ID" \| "INSTAGRAM_THREAD_ID" \| "LINKEDIN_ID" \| "LINKEDIN_THREAD_ID" \| "GROUP_THREAD"` | Yes | — | — |
| `result.data.items[].to_attendees` | `array` | No | — | — |
| `result.data.items[].to_attendees[].display_name` | `string` | No | — | — |
| `result.data.items[].to_attendees[].profile_picture` | `string` | No | — | — |
| `result.data.items[].to_attendees[].identifier` | `string` | Yes | — | — |
| `result.data.items[].to_attendees[].identifier_type` | `"CHAT_ATTENDEE_ID" \| "PHONE_NUMBER" \| "EMAIL_ADDRESS" \| "MESSENGER_ID" \| "MESSENGER_THREAD_ID" \| "TIKTOK_ID" \| "TIKTOK_THREAD_ID" \| "TWITTER_ID" \| "TWITTER_THREAD_ID" \| "INSTAGRAM_ID" \| "INSTAGRAM_THREAD_ID" \| "LINKEDIN_ID" \| "LINKEDIN_THREAD_ID" \| "GROUP_THREAD"` | Yes | — | — |
| `result.data.items[].cc_attendees` | `array` | No | — | — |
| `result.data.items[].cc_attendees[].display_name` | `string` | No | — | — |
| `result.data.items[].cc_attendees[].profile_picture` | `string` | No | — | — |
| `result.data.items[].cc_attendees[].identifier` | `string` | Yes | — | — |
| `result.data.items[].cc_attendees[].identifier_type` | `"CHAT_ATTENDEE_ID" \| "PHONE_NUMBER" \| "EMAIL_ADDRESS" \| "MESSENGER_ID" \| "MESSENGER_THREAD_ID" \| "TIKTOK_ID" \| "TIKTOK_THREAD_ID" \| "TWITTER_ID" \| "TWITTER_THREAD_ID" \| "INSTAGRAM_ID" \| "INSTAGRAM_THREAD_ID" \| "LINKEDIN_ID" \| "LINKEDIN_THREAD_ID" \| "GROUP_THREAD"` | Yes | — | — |
| `result.data.items[].bcc_attendees` | `array` | No | — | — |
| `result.data.items[].bcc_attendees[].display_name` | `string` | No | — | — |
| `result.data.items[].bcc_attendees[].profile_picture` | `string` | No | — | — |
| `result.data.items[].bcc_attendees[].identifier` | `string` | Yes | — | — |
| `result.data.items[].bcc_attendees[].identifier_type` | `"CHAT_ATTENDEE_ID" \| "PHONE_NUMBER" \| "EMAIL_ADDRESS" \| "MESSENGER_ID" \| "MESSENGER_THREAD_ID" \| "TIKTOK_ID" \| "TIKTOK_THREAD_ID" \| "TWITTER_ID" \| "TWITTER_THREAD_ID" \| "INSTAGRAM_ID" \| "INSTAGRAM_THREAD_ID" \| "LINKEDIN_ID" \| "LINKEDIN_THREAD_ID" \| "GROUP_THREAD"` | Yes | — | — |
| `result.data.items[].reply_to_attendees` | `array` | No | — | — |
| `result.data.items[].reply_to_attendees[].display_name` | `string` | No | — | — |
| `result.data.items[].reply_to_attendees[].profile_picture` | `string` | No | — | — |
| `result.data.items[].reply_to_attendees[].identifier` | `string` | Yes | — | — |
| `result.data.items[].reply_to_attendees[].identifier_type` | `"CHAT_ATTENDEE_ID" \| "PHONE_NUMBER" \| "EMAIL_ADDRESS" \| "MESSENGER_ID" \| "MESSENGER_THREAD_ID" \| "TIKTOK_ID" \| "TIKTOK_THREAD_ID" \| "TWITTER_ID" \| "TWITTER_THREAD_ID" \| "INSTAGRAM_ID" \| "INSTAGRAM_THREAD_ID" \| "LINKEDIN_ID" \| "LINKEDIN_THREAD_ID" \| "GROUP_THREAD"` | Yes | — | — |
| `result.data.items[].subject` | `string` | Yes | — | — |
| `result.data.items[].has_attachments` | `boolean` | Yes | — | — |
| `result.data.items[].origin` | `"unipile" \| "external"` | Yes | — | — |
| `result.data.items[].in_reply_to` | `object` | No | — | — |
| `result.data.items[].in_reply_to.message_id` | `string` | Yes | — | — |
| `result.data.items[].in_reply_to.id` | `string` | Yes | — | A unique identifier. |
| `result.data.items[].tracking_id` | `string` | No | — | — |

The table shows the first 50 fields. Use the live contract below for every field.

> [!NOTE]
>
> This output schema is too large for an inline display. Read the complete live contract with `deepline describe unipile_list_emails --json`.

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Unipile provider guide](https://deepline.com/docs/providers/unipile/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.