---
title: Emails
description: "Emails: list, get, create, update and delete, plus batch operations."
canonical: https://developers.coevera.com/reference/rest/emails/
section: rest
verification: schema
generatedFrom: spec 5e43371 (2026-10-16)
publisher: Coevera
---

# Emails

Emails: list, get, create, update and delete, plus batch operations.

Family: Activities and communication. GraphQL: [email](https://developers.coevera.com/reference/graphql/email.md). Base URL: `https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}`.

| Method | Path | Operation |
| --- | --- | --- |
| GET | `/entities/Emails` | List Emails |
| POST | `/entities/Emails` | Create Email |
| GET | `/entities/Emails/{id}` | Get Email |
| PATCH | `/entities/Emails/{id}` | Update Email |
| DELETE | `/entities/Emails/{id}` | Delete Email |
| POST | `/entities/Emails/batch-modify` | Create or update Emails in a batch |
| POST | `/entities/Emails/batch-delete` | Delete Emails in a batch |
| POST | `/entities/Emails/batch-restore` | Restore deleted Emails |

## List Emails

`GET /entities/Emails`

Returns the Emails the API application can read, one page at a time. In the list envelope, `total` counts every match and `page_info` pages through them.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `include-deleted` | query | boolean | Include soft-deleted records. Lists only; get-by-id refuses it. |
| `first` | query | integer | Page size. Default 30, maximum 100; a larger value is refused with HTTP 400, code 117. (default 30, 1 to 100) |
| `last` | query | integer | Return the last N records of the result; together with `first`, the last N of the first M. Maximum 100. (1 to 100) |
| `before` | query | string | Cursor from `page_info.start_cursor`, to page backwards. URL-encode it. |
| `after` | query | string | Cursor from `page_info.end_cursor` of the previous page. URL-encode it: cursors are base64, and a raw + becomes a space. |
| `expand` | query | string | Related records to return inline instead of their URIs, comma-separated; dots reach nested relations, as in `account_relations.account`. |
| `order-by` | query | string | Fields to sort by, comma-separated. A leading - sorts descending, as in `-modified`; dotted paths sort by related fields. |
| `filter` | query | object | `filter[field]=value`. Separate several values with a raw comma (OR), as in `filter[name]=north,south`. Encode a comma that belongs to a value as %2C. URLSearchParams and Python requests encode every comma, so build the filter part of the query string yourself. Dotted paths filter on related records, as in `filter[owner.email]`. Encode a + in a value as %2B: query values are form-decoded, so a raw + becomes a space. |
| `filter-op` | query | object | `filter-op[field]=operator`, one per field: eq (the default), ieq, not-eq, not-ieq, contains, icontains, starts, istarts, ends, iends, gt, gte, lt, lte, between, null, not-null, empty and not-empty. null, not-null, empty and not-empty take no filter value; gt, gte, lt and lte take exactly one. |
| `load-only` | query | string | Fields to return, comma-separated (raw or encoded commas both work here); dots select nested fields, as in `owner.id`. All fields are returned without it. Lists only: get-by-id refuses it with HTTP 400, code 118. |

Responses: 200 (Page of Email records.: `success`, `total`, `page_info`, `data`), 400, 401, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails?first=10' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Create Email

`POST /entities/Emails`

Creates one record and answers 201 with it.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |

Request body: The new record's fields. Relations are set by id. Schema `createEmailInput`. Required: `direction`, `uid`.

Responses: 201 (The created Email record.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "direction": 1,
  "uid": "Northwind uid"
}'
```

## Get Email

`GET /entities/Emails/{id}`

Returns one record by id. `expand` returns related records inline instead of their URIs.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Email record to retrieve. |
| `expand` | query | string | Related records to return inline instead of their URIs, comma-separated; dots reach nested relations. The only parameter this call accepts. |

Responses: 200 (The Email record.: `success`, `data`), 400, 401, 404, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001?expand=owner' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Update Email

`PATCH /entities/Emails/{id}`

Changes the fields you send and leaves the rest as they are; there is no PUT.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Email record to update. |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |

Request body: The fields to change. Schema `updateEmailInput`.

Responses: 200 (The changed Email record.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001' \
  --request PATCH \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "Follow up with Northwind Analytics (email) (renamed)"
}'
```

## Delete Email

`DELETE /entities/Emails/{id}`

Deletes one record and answers with its id.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Email record to delete. |

Responses: 200 (Deletion confirmation.: `success`, `data`), 400, 401, 404, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001' \
  --request DELETE \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Create or update Emails in a batch

`POST /entities/Emails/batch-modify`

An item with an `id` updates that record; an item without one creates a record. By default one invalid item fails the whole call with HTTP 422 and nothing is written; with `rollback-method=1` the response has an id or an error for each item, in input order.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of records: an item with an `id` updates, an item without one creates. Schema `batchEmailInput`. Required: `direction`, `uid`.

Responses: 200 (Result per item, in request order: the id of the created or updated record, or the error.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-modify' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "direction": 1,
    "uid": "Northwind uid"
  },
  {
    "id": "7c000000-0000-4000-a000-000000000001",
    "subject": "Follow up with Northwind Analytics (email) (renamed)"
  }
]'
```

## Delete Emails in a batch

`POST /entities/Emails/batch-delete`

Deletes the records whose ids are in the body, a JSON array. By default an unknown id fails the whole call with HTTP 404.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of ids.

Responses: 200 (Result per id, in request order: the id of the deleted record, or the error.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-delete' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  "7c000000-0000-4000-a000-000000000001",
  "7c000000-0000-4000-a000-000000000002"
]'
```

## Restore deleted Emails

`POST /entities/Emails/batch-restore`

Restores the deleted records whose ids are in the body, a JSON array.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of ids.

Responses: 200 (Result per id, in request order: the id of the restored record, or the error.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-restore' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  "7c000000-0000-4000-a000-000000000001",
  "7c000000-0000-4000-a000-000000000002"
]'
```

## Email fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | uuid | Read-only. Unique identifier of entity. |
| `direction` | integer | Required on create. Direction of the email (Incoming, Outgoing). Values: 1 OutgoingEmail, 2 IncomingEmail. |
| `uid` | string | Required on create. IMAP UID of the email on the source mailbox. |
| `additional_headers` | object | Extra raw email headers preserved from the source message, as a JSON object mapping each header name to a string or a list of strings. |
| `bcc` | string | Comma-separated list of blind-carbon-copy recipients. |
| `body` | string | HTML body of the email. |
| `body_summary` | string | Plain-text summary of the email body. |
| `cc` | string | Comma-separated list of carbon-copy recipients. |
| `company_email_id` | uuid → CompanyEmails | Id of the company email used as the From / Reply-To. |
| `content_share_mode` | integer | How the email body is shared with non-owners (e.g. Values: 0 Custom, 1 Private, 2 Public. |
| `content_type` | string | MIME content type of the body (e.g. |
| `date_sent` | date-time | Timestamp the email was sent. |
| `draft_parent_email_id` | uuid → Emails | Id of the original email a draft was started from (reply/forward source), or empty for a standalone draft. |
| `draft_settings` | object | Serialised state of the Create Email dialogue for a draft, as a JSON object, so the composer can be re-opened verbatim. |
| `error_code` | integer | Numeric error code recorded when the email failed to send. |
| `is_draft` | boolean | True when this email is an unsent draft. |
| `is_tracked` | boolean | True when delivery tracking is enabled. |
| `original_id` | string | External identifier of the email on the source mailbox (e.g. |
| `owner_id` | uuid → Clients | Id of the email owner. |
| `parent_email_id` | uuid → Emails | Id of the parent (master) email. |
| `schedule_settings` | object | Scheduling configuration for delayed sending, as a JSON object; next_schedule is a numeric timestamp and recipients/cc/bcc are lists. |
| `send_at` | date-time | Timestamp at which a scheduled email is queued to be sent. |
| `sender` | string | Sender address as it appeared on the email (free-text "From" header). |
| `sender_account_id` | uuid → Accounts | Id of the matched sender account. |
| `sender_client_id` | uuid → Clients | Id of the matched sender user. |
| `sender_contact_id` | uuid → Contacts | Id of the matched sender contact. |
| `sender_email_account_id` | uuid | Id of the personal email-integration account that sent this email. |
| `sentiment` | integer | Tone of the email (Negative, Neutral or Positive) as assessed by AI from its content; empty until assessed. Values: 0 Negative, 1 Neutral, 2 Positive. |
| `share_mode` | integer | Sharing model for the email envelope (e.g. Values: 0 Standard, 1 Private, 2 AllView, 3 AllEdit. |
| `subject` | string | Name of the entity and its default text representation. |
| `template_id` | uuid → EmailTemplates | Id of the email template. |
| `thread_id` | uuid | Identifier grouping emails belonging to the same conversation thread. |
| `to` | string | Comma-separated list of primary recipients. |
| `type` | integer | Whether the email is an individual email (Standard) or part of a mass email (Mass). Values: 1 Standard, 2 Mass. |
| `revision` | integer | Revision when entity was lastly changed. |
| `sharing_units` | array of uri → MessageSharingSalesUnitRelations | Sales units that have been granted shared access to this email envelope. |
| `sharing_clients` | array of uri → MessageSharingClientRelations | Users that have been granted shared access to this email envelope. |
| `content_sharing_units` | array of uri → EmailContentSharingSalesUnitRelations | Sales units that have been granted access to the email body when content_share_mode is restricted. |
| `content_sharing_clients` | array of uri → EmailContentSharingClientRelations | Users that have been granted access to the email body when content_share_mode is restricted. |
| `account_relations` | array of uri → MessageRelations | Accounts this email is linked to. |
| `contact_relations` | array of uri → MessageRelations | Contacts this email is linked to. |
| `project_relations` | array of uri → MessageRelations | Projects this email is linked to. |
| `custom_entity_relations` | array of uri → MessageRelations | Custom entity records this email is linked to. |
| `lead_relations` | array of uri → MessageRelations | Leads this email is linked to. |
| `opportunity_relations` | array of uri → MessageRelations | Opportunities this email is linked to. |
| `quote_relations` | array of uri → MessageRelations | Quotes this email is linked to. |
| `tags` | array of uri → TagRelations | Tag labels applied to this email. |
| `documents` | array of uri → CloudObjectRelations | Attachments and other documents linked to this email. |
| `is_delete_protected` | boolean | Read-only. True when the record is protected against deletion because it must always exist in the space. |
| `is_deleted` | boolean | Read-only. Specifies if the entity is considered deleted. |
| `modified` | date-time | Read-only. Last modification time. |
| `created` | date-time | Read-only. Creation time. |
| `company_email` | uri → CompanyEmails | Read-only. Configured company email used as the From / Reply-To. |
| `draft_parent_email` | uri → Emails | Read-only. The original email a draft was started from (reply/forward source), or empty for a standalone draft. |
| `owner` | uri → Clients | Read-only. Sales user who owns this email. |
| `parent_email` | uri → Emails | Read-only. For mass emails: the master email this copy was generated from. |
| `sender_account` | uri → Accounts | Read-only. Account record matched as the sender, or empty when the sender does not match an existing Account. |
| `sender_client` | uri → Clients | Read-only. Internal user matched as the sender, or empty when the sender is external. |
| `sender_contact` | uri → Contacts | Read-only. Contact record matched as the sender, or empty when the sender does not match an existing Contact. |
| `template` | uri → EmailTemplates | Read-only. Email template used to compose this email, or empty when none was used. |
| `table_name` | string | Read-only. Discriminator identifying the concrete record type — always "email" for Email records. |
| `is_favorite` | boolean | Read-only. True when the current authenticated user has marked this email as favorite. |
| `mailbox_ids` | array of uuid | Read-only. Ids of the mailboxes (company or personal) the email envelope belongs to, aggregated from the active email_mailbox_relation rows. |

Custom fields appear in your space's live spec: `GET /api/v100/rest/spaces/{space_id}/openapi.json` with your credentials.

## Errors

Every error body has `success: false`, `http_status`, `code`, `name` and `message`. Branch on `code`: the status alone does not tell a missing permission from a bad parameter.

| HTTP | When |
| --- | --- |
| 400 | Bad request: a bad or unknown parameter (codes 117, 118), a missing permission (code 50), conflicting data (code 2002) or any other API error. The REST API answers 400 where others answer 403 or 409; check `code`. |
| 401 | Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED). |
| 404 | No such record or entity (code 143 ERROR_NO_ENTITY, or 2006 ERROR_UNKNOWN_TYPE). |
| 422 | Validation failed (code 40000, with the failing fields) or a required parameter is missing (code 119). By default one failed item fails a whole batch and nothing is written. |
| 429 | Too many requests (code 182). Wait for the seconds in Retry-After, then retry. |
| 500 | Unexpected server error (code 1000, ERROR_UNKNOWN). |

All error codes: https://developers.coevera.com/reference/errors.md; how to handle them: https://developers.coevera.com/concepts/errors.md

## Webhook events for emails

`Email.Create`, `Email.Delete`, `Email.DocumentLinked`, `Email.Update`. Payloads: https://developers.coevera.com/webhooks/events.md

Subscribe with [Create a webhook](https://developers.coevera.com/reference/rest/webhooks.md).