--- title: "Emails.batch_create_or_update" method: POST path: "/entities/Emails/batch-modify" tags: ["Email"] --- # Emails.batch_create_or_update `POST /entities/Emails/batch-modify` ## Request - Base URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id` - URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id/entities/Emails/batch-modify` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates or updates Email records in one request: an item with an id updates that record, an item without one creates a new record. ## Query parameters - `validation-level` integer - `rollback-method` 0 | 1 ## Request body - BatchEmailInput[] - `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. Returned only to users with read permission on the email content; otherwise empty. - `body_summary` string: Plain-text summary of the email body. Returned only to users with read permission on the email content; otherwise empty. - `cc` string: Comma-separated list of carbon-copy recipients. - `company_email_id` string, uuid: Id of the company email used as the From / Reply-To. Empty when sent from the user mailbox. - `content_share_mode` 0 | 1 | 2: How the email body is shared with non-owners (e.g. Private hides the body, Public makes it visible to anyone with read access on the email envelope). Integer enum value: 0 - Custom, 1 - Private, 2 - Public - `content_type` string: MIME content type of the body (e.g. text/html, text/plain). - `date_sent` string, date-time: Timestamp the email was sent. Empty for drafts and scheduled emails not yet sent. - `direction` 1 | 2: Direction of the email (Incoming, Outgoing). Integer enum value: 1 - OutgoingEmail, 2 - IncomingEmail - `draft_parent_email_id` string, uuid: 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. Empty for non-draft emails. - `error_code` integer: Numeric error code recorded when the email failed to send. Zero when no error occurred. - `is_draft` boolean: True when this email is an unsent draft. Drafts have no date_sent/send_at and are excluded from the sent/scheduled streams. - `is_tracked` boolean: True when delivery tracking is enabled. Tracked emails generate EmailEvent records on open/click. - `original_id` string: External identifier of the email on the source mailbox (e.g. IMAP Message-ID). Used to deduplicate when re-syncing. - `owner_id` string, uuid: Id of the email owner. - `parent_email_id` string, uuid: 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` string, date-time: Timestamp at which a scheduled email is queued to be sent. Empty for immediately-sent emails. - `sender` string: Sender address as it appeared on the email (free-text "From" header). - `sender_account_id` string, uuid: Id of the matched sender account. - `sender_client_id` string, uuid: Id of the matched sender user. - `sender_contact_id` string, uuid: Id of the matched sender contact. - `sender_email_account_id` string, uuid: Id of the personal email-integration account that sent this email. - `sentiment` 0 | 1 | 2: Tone of the email (Negative, Neutral or Positive) as assessed by AI from its content; empty until assessed. Returned only to users with read permission on the email content. Integer enum value: 0 - Negative, 1 - Neutral, 2 - Positive - `share_mode` 0 | 1 | 2 | 3: Sharing model for the email envelope (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `subject` string: Name of the entity and its default text representation. - `template_id` string, uuid: Id of the email template. - `thread_id` string, uuid: Identifier grouping emails belonging to the same conversation thread. - `to` string: Comma-separated list of primary recipients. - `type` 1 | 2: Whether the email is an individual email (Standard) or part of a mass email (Mass). Integer enum value: 1 - Standard, 2 - Mass - `uid` string: IMAP UID of the email on the source mailbox. - `revision` integer: Revision when entity was lastly changed. - `sharing_units` object[]: Sales units that have been granted shared access to this email envelope. - `id` string, uuid: Id of the related MessageSharingSalesUnitRelation record. - `sharing_clients` object[]: Users that have been granted shared access to this email envelope. - `id` string, uuid: Id of the related MessageSharingClientRelation record. - `content_sharing_units` object[]: Sales units that have been granted access to the email body when content_share_mode is restricted. - `id` string, uuid: Id of the related EmailContentSharingSalesUnitRelation record. - `content_sharing_clients` object[]: Users that have been granted access to the email body when content_share_mode is restricted. - `id` string, uuid: Id of the related EmailContentSharingClientRelation record. - `account_relations` object[]: Accounts this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `contact_relations` object[]: Contacts this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `project_relations` object[]: Projects this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `custom_entity_relations` object[]: Custom entity records this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `lead_relations` object[]: Leads this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `opportunity_relations` object[]: Opportunities this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `quote_relations` object[]: Quotes this email is linked to. - `id` string, uuid: Id of the related MessageRelation record. - `tags` object[]: Tag labels applied to this email. Visible only to users that can read the email body. - `id` string, uuid: Id of the related TagRelation record. - `documents` object[]: Attachments and other documents linked to this email. - `id` string, uuid: Id of the related CloudObjectRelation record. - `id` string, uuid: ID of object to update. ## Response `200` Result per item, in request order: the id of the created or updated record, or the error. - object - `success` boolean: True when the request succeeded; false on error. - `data` union[] - union - string, uuid: Id of the created or updated record. - Error: The body of every REST error. `code` and `name` are stable identifiers; `message` is for people. The full list of codes is at https://developers.coevera.com/reference/errors/. - `http_status` integer, required: HTTP status code. - `code` integer: Numeric code of the API error. - `name` string: Name of the API error. - `message` string: Message describing the error. - `success` boolean, required: Always false on error. ## Other responses - `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). - `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). --- [API](https://skmtc.dev/coevera/apis/coevera-crm-api.md) - [All operations](https://skmtc.dev/coevera/apis/coevera-crm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coevera/apis/coevera-crm-api/revisions/40ebbc83f179?raw)