Developers
ChangelogSupportcoevera.comGet API keys
Set your API contextPick a region and space ID once. Every sample fills in your base URL.
Where do I find these?

In Coevera: open your space's API application and choose Show Access. It shows the space ID and the base URL, whose host starts with your region.

From the API: if you know the space ID, the discovery endpoint GET /api/discovery/spaces/{space_id} returns its region and base URLs, without credentials.

Only the region and space ID are kept, in this browser. Never paste a key or password here.

More in the quickstart

REST APIActivities and communicationEmails

Emails

View as Markdown/reference/rest/emails.mdOpen in ClaudeAsk Claude about this pageOpen in ChatGPTAsk ChatGPT about this page

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

The summaries on this page are generated from the specification; written descriptions come with the next releases of the reference.

MethodPathOperation
GET/entities/EmailsList Emails
POST/entities/EmailsCreate Email
GET/entities/Emails/{id}Get Email
PATCH/entities/Emails/{id}Update Email
DEL/entities/Emails/{id}Delete Email
POST/entities/Emails/batch-modifyCreate or update Emails in a batch
POST/entities/Emails/batch-deleteDelete Emails in a batch
POST/entities/Emails/batch-restoreRestore deleted Emails

GET List 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.

Query parameters

NameTypeDescription
include-deletedbooleanInclude soft-deleted records. Lists only; get-by-id refuses it.
firstintegerPage size. Default 30, maximum 100; a larger value is refused with HTTP 400, code 117.
lastintegerReturn the last N records of the result; together with first, the last N of the first M. Maximum 100.
beforestringCursor from page_info.start_cursor, to page backwards. URL-encode it.
afterstringCursor from page_info.end_cursor of the previous page. URL-encode it: cursors are base64, and a raw + becomes a space.
expandstringRelated records to return inline instead of their URIs, comma-separated; dots reach nested relations, as in account_relations.account.
order-bystringFields to sort by, comma-separated. A leading - sorts descending, as in -modified; dotted paths sort by related fields.
filterobjectfilter[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-opobjectfilter-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-onlystringFields 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 Bad request 401 Not authenticated 429 Rate limited 500 Server error

GET /entities/Emails
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails?first=10' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails?first=10', {
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`)
  }
})
import os

import requests

response = requests.get(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails",
    params={
      "first": "10"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"])
)

POST Create Email

Creates one record and answers 201 with it.

Query parameters

NameTypeDescription
validation-levelintegerBit 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; the fields are in Email fields. Required: direction, uid.

Responses

201 The created Email record.: success, data 400 Bad request 401 Not authenticated 422 Validation failed 429 Rate limited 500 Server error

POST /entities/Emails
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"
}'
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails', {
  method: 'POST',
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    direction: 1,
    uid: 'Northwind uid'
  })
})
import os

import requests

response = requests.post(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails",
    headers={
      "Content-Type": "application/json"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"]),
    json={
      "direction": 1,
      "uid": "Northwind uid"
    }
)

GET Get Email

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

Path parameters

NameTypeDescription
idstring (uuid)Id of the Email record to retrieve. Required

Query parameters

NameTypeDescription
expandstringRelated 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 Bad request 401 Not authenticated 404 Not found 429 Rate limited 500 Server error

GET /entities/Emails/{id}
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"
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001?expand=owner', {
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`)
  }
})
import os

import requests

response = requests.get(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001",
    params={
      "expand": "owner"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"])
)

PATCH Update Email

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

Path parameters

NameTypeDescription
idstring (uuid)Id of the Email record to update. Required

Query parameters

NameTypeDescription
validation-levelintegerBit 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; the fields are in Email fields.

Responses

200 The changed Email record.: success, data 400 Bad request 401 Not authenticated 404 Not found 422 Validation failed 429 Rate limited 500 Server error

PATCH /entities/Emails/{id}
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)"
}'
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001', {
  method: 'PATCH',
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: 'Follow up with Northwind Analytics (email) (renamed)'
  })
})
import os

import requests

response = requests.patch(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001",
    headers={
      "Content-Type": "application/json"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"]),
    json={
      "subject": "Follow up with Northwind Analytics (email) (renamed)"
    }
)

DEL Delete Email

Deletes one record and answers with its id.

Path parameters

NameTypeDescription
idstring (uuid)Id of the Email record to delete. Required

Responses

200 Deletion confirmation.: success, data 400 Bad request 401 Not authenticated 404 Not found 429 Rate limited 500 Server error

DEL /entities/Emails/{id}
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"
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001', {
  method: 'DELETE',
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`)
  }
})
import os

import requests

response = requests.delete(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/7c000000-0000-4000-a000-000000000001",
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"])
)

POST Create or update Emails in a batch

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.

Query parameters

NameTypeDescription
validation-levelintegerBit 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-methodinteger0, 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.

Request body

A JSON array of records: an item with an id updates, an item without one creates. Schema batchEmailInput; the fields are in Email fields. 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 Bad request 401 Not authenticated 422 Validation failed 429 Rate limited 500 Server error

POST /entities/Emails/batch-modify
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)"
  }
]'
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-modify', {
  method: 'POST',
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      direction: 1,
      uid: 'Northwind uid'
    },
    {
      id: '7c000000-0000-4000-a000-000000000001',
      subject: 'Follow up with Northwind Analytics (email) (renamed)'
    }
  ])
})
import os

import requests

response = requests.post(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-modify",
    headers={
      "Content-Type": "application/json"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"]),
    json=[
      {
        "direction": 1,
        "uid": "Northwind uid"
      },
      {
        "id": "7c000000-0000-4000-a000-000000000001",
        "subject": "Follow up with Northwind Analytics (email) (renamed)"
      }
    ]
)

POST Delete Emails in a batch

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

Query parameters

NameTypeDescription
rollback-methodinteger0, 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.

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 Bad request 401 Not authenticated 404 Not found 422 Validation failed 429 Rate limited 500 Server error

POST /entities/Emails/batch-delete
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"
]'
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-delete', {
  method: 'POST',
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(['7c000000-0000-4000-a000-000000000001', '7c000000-0000-4000-a000-000000000002'])
})
import os

import requests

response = requests.post(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-delete",
    headers={
      "Content-Type": "application/json"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"]),
    json=[
      "7c000000-0000-4000-a000-000000000001",
      "7c000000-0000-4000-a000-000000000002"
    ]
)

POST Restore deleted Emails

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

Query parameters

NameTypeDescription
rollback-methodinteger0, 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.

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 Bad request 401 Not authenticated 404 Not found 422 Validation failed 429 Rate limited 500 Server error

POST /entities/Emails/batch-restore
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"
]'
fetch('https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-restore', {
  method: 'POST',
  headers: {
    Authorization: "Basic " + btoa(`${process.env.COEVERA_API_KEY}:${process.env.COEVERA_API_SECRET}`),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(['7c000000-0000-4000-a000-000000000001', '7c000000-0000-4000-a000-000000000002'])
})
import os

import requests

response = requests.post(
    "https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Emails/batch-restore",
    headers={
      "Content-Type": "application/json"
    },
    auth=(os.environ["COEVERA_API_KEY"], os.environ["COEVERA_API_SECRET"]),
    json=[
      "7c000000-0000-4000-a000-000000000001",
      "7c000000-0000-4000-a000-000000000002"
    ]
)

Email fields

FieldTypeNotes
iduuidRead-only Unique identifier of entity.
directionintegerRequired on create Direction of the email (Incoming, Outgoing).1 OutgoingEmail · 2 IncomingEmail
uidstringRequired on create IMAP UID of the email on the source mailbox.
additional_headersobjectExtra raw email headers preserved from the source message, as a JSON object mapping each header name to a string or a list of strings.
bccstringComma-separated list of blind-carbon-copy recipients.
bodystringHTML body of the email.
body_summarystringPlain-text summary of the email body.
ccstringComma-separated list of carbon-copy recipients.
company_email_iduuid → CompanyEmailsId of the company email used as the From / Reply-To.
content_share_modeintegerHow the email body is shared with non-owners (e.g.0 Custom · 1 Private · 2 Public
content_typestringMIME content type of the body (e.g.
date_sentdate-timeTimestamp the email was sent.
draft_parent_email_iduuid → EmailsId of the original email a draft was started from (reply/forward source), or empty for a standalone draft.
draft_settingsobjectSerialised state of the Create Email dialogue for a draft, as a JSON object, so the composer can be re-opened verbatim.
error_codeintegerNumeric error code recorded when the email failed to send.
Show all 63 fields
FieldTypeNotes
is_draftbooleanTrue when this email is an unsent draft.
is_trackedbooleanTrue when delivery tracking is enabled.
original_idstringExternal identifier of the email on the source mailbox (e.g.
owner_iduuid → ClientsId of the email owner.
parent_email_iduuid → EmailsId of the parent (master) email.
schedule_settingsobjectScheduling configuration for delayed sending, as a JSON object; next_schedule is a numeric timestamp and recipients/cc/bcc are lists.
send_atdate-timeTimestamp at which a scheduled email is queued to be sent.
senderstringSender address as it appeared on the email (free-text "From" header).
sender_account_iduuid → AccountsId of the matched sender account.
sender_client_iduuid → ClientsId of the matched sender user.
sender_contact_iduuid → ContactsId of the matched sender contact.
sender_email_account_iduuidId of the personal email-integration account that sent this email.
sentimentintegerTone of the email (Negative, Neutral or Positive) as assessed by AI from its content; empty until assessed.0 Negative · 1 Neutral · 2 Positive
share_modeintegerSharing model for the email envelope (e.g.0 Standard · 1 Private · 2 AllView · 3 AllEdit
subjectstringName of the entity and its default text representation.
template_iduuid → EmailTemplatesId of the email template.
thread_iduuidIdentifier grouping emails belonging to the same conversation thread.
tostringComma-separated list of primary recipients.
typeintegerWhether the email is an individual email (Standard) or part of a mass email (Mass).1 Standard · 2 Mass
revisionintegerRevision when entity was lastly changed.
sharing_unitsarray of uri → MessageSharingSalesUnitRelationsSales units that have been granted shared access to this email envelope.
sharing_clientsarray of uri → MessageSharingClientRelationsUsers that have been granted shared access to this email envelope.
content_sharing_unitsarray of uri → EmailContentSharingSalesUnitRelationsSales units that have been granted access to the email body when content_share_mode is restricted.
content_sharing_clientsarray of uri → EmailContentSharingClientRelationsUsers that have been granted access to the email body when content_share_mode is restricted.
account_relationsarray of uri → MessageRelationsAccounts this email is linked to.
contact_relationsarray of uri → MessageRelationsContacts this email is linked to.
project_relationsarray of uri → MessageRelationsProjects this email is linked to.
custom_entity_relationsarray of uri → MessageRelationsCustom entity records this email is linked to.
lead_relationsarray of uri → MessageRelationsLeads this email is linked to.
opportunity_relationsarray of uri → MessageRelationsOpportunities this email is linked to.
quote_relationsarray of uri → MessageRelationsQuotes this email is linked to.
tagsarray of uri → TagRelationsTag labels applied to this email.
documentsarray of uri → CloudObjectRelationsAttachments and other documents linked to this email.
is_delete_protectedbooleanRead-only True when the record is protected against deletion because it must always exist in the space.
is_deletedbooleanRead-only Specifies if the entity is considered deleted.
modifieddate-timeRead-only Last modification time.
createddate-timeRead-only Creation time.
company_emailuri → CompanyEmailsRead-only Configured company email used as the From / Reply-To.
draft_parent_emailuri → EmailsRead-only The original email a draft was started from (reply/forward source), or empty for a standalone draft.
owneruri → ClientsRead-only Sales user who owns this email.
parent_emailuri → EmailsRead-only For mass emails: the master email this copy was generated from.
sender_accounturi → AccountsRead-only Account record matched as the sender, or empty when the sender does not match an existing Account.
sender_clienturi → ClientsRead-only Internal user matched as the sender, or empty when the sender is external.
sender_contacturi → ContactsRead-only Contact record matched as the sender, or empty when the sender does not match an existing Contact.
templateuri → EmailTemplatesRead-only Email template used to compose this email, or empty when none was used.
table_namestringRead-only Discriminator identifying the concrete record type — always "email" for Email records.
is_favoritebooleanRead-only True when the current authenticated user has marked this email as favorite.
mailbox_idsarray of uuidRead-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: fetch it 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. All codes: error codes; how to handle them: Errors.

HTTPWhen
400Bad 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.
401Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED).
404No such record or entity (code 143 ERROR_NO_ENTITY, or 2006 ERROR_UNKNOWN_TYPE).
422Validation 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.
429Too many requests (code 182). Wait for the seconds in Retry-After, then retry.
500Unexpected server error (code 1000, ERROR_UNKNOWN).

Webhook events for emails

Email.Create Email.Delete Email.DocumentLinked Email.Update See payloads

Subscribe with Create a webhook.