ConnectCloud Developers

Send an e-mail to a lead or contact (tenant:crm:write)

POST /api/crm/v1/activities/mail

Module: CRM · operationId: sendContactMail · Tag: Activities · Auth: access token (Authorization: Bearer <accessToken>)

Sends a personal e-mail of the calling person through the tenant's default mail channel (comms, system template crm.contact_mail: subject, the plain-text body – Markdown is sent as written –, then the sender's name and e-mail) and records it as an EMAIL activity of the lead, opportunity or address (at least one is required, 400 activity_link_required). The mail is queued in the transaction that stores the activity and delivered right after; meta holds to, template, idempotencyKey and commandId (the queued delivery). marketingOptOut does not stop a personal mail; an anonymised lead is 409 (lead_anonymized). Without mail configured the answer is 503 (mail_unavailable). With an Idempotency-Key a repeated request answers the activity of the first one and sends nothing. Emits crm.activity.created; an e-mail to a lead counts for its score.

Parameters

Name In Type Required Description
Idempotency-Key header string Makes a retry harmless (at most 128 characters, per person). (max length 128)

Request body

application/json (required)

  • body (string, required): Plain text; Markdown is sent as written. (max length 4000)
  • subject (string, required): One line. (max length 255)
  • to (string (email), required): Recipient e-mail address. (max length 255)
  • addressId (string (uuid)): A masterdata address of the tenant (checked).
  • leadId (string (uuid)): Lead the mail is about (a lead of the tenant).
  • opportunityId (string (uuid)): Opportunity the mail is about.

Example:

{
  "body": "Guten Tag Frau Gaßner,\n\nwie besprochen erhalten Sie anbei unser Angebot AN-2026-0012.\n\nViele Grüße\nLena Vogel",
  "leadId": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f",
  "opportunityId": "7d9f1b3d-5e7a-4c9b-8f1d-5c7e9a1b3d5f",
  "subject": "Ihr Angebot für das WLAN in Sudhaus und Lager",
  "to": "eva.gassner@brauerei-gassner.example"
}

Responses

  • 201 The EMAIL activity of the queued mail (application/json)
  • 400 Invalid input (invalid): field names the first invalid field, details.fields every one (JSON paths for bodies, parameter names for the query). Some refusals have their own code (invalid_sort, invalid_stages, invalid_custom_fields, convert_target_required, invalid_csv, …). (application/json)
  • 401 Missing, invalid or expired token (no body).
  • 403 The token lacks the permission (insufficient permissions) or has no active tenant. (application/json)
  • 409 The state of the record (or the tenant's settings) does not allow the request; code says why. (application/json)
  • 422 A referenced record (lead, masterdata address) does not exist in the tenant. (application/json)
  • 500 Unexpected error; details are only logged. (application/json)
  • 503 The CRM cannot send mail (mail_unavailable). (application/json)

Fields of the 201 answer:

  • bookedMinutes (integer, nullable, required, read-only): Work HR booked on the activity (subject crm:activity:<id>, worked minus breaks, ADR 0040); filled by GET /activities/{id} and the activity list, null there when HR does not answer (never an error) and in answers of writes.
  • createdAt (string (date-time), required): Creation time.
  • customerNo (string, required): Customer number of the tenant.
  • id (string (uuid), required): Id of the activity.
  • kind (ActivityKind, required): SYSTEM entries are history written by the CRM and cannot be created or changed. (one of NOTE, CALL, MEETING, EMAIL, TASK, SYSTEM)
  • meta (object, required): Details of SYSTEM entries (for example the old and new stage); of a tracked interaction interactionId, provider, summary and transcript (left out by lists); empty otherwise.
  • subject (string, required): Subject (one line).
  • tenantName (string, required): Tenant name.
  • updatedAt (string (date-time), required): Time of the last change.
  • addressId (string (uuid)): Masterdata address the activity belongs to; omitted when not set.
  • assigneeEmail (string): Employee the task is assigned to.
  • body (string): Omitted when not set (and after anonymisation).
  • campaignId (string (uuid)): Campaign the activity belongs to; omitted when not set.
  • createdBy (string): E-mail of the creating person; omitted for system entries.
  • createdByName (string): Name of the creating person; omitted when not known.
  • doneAt (string (date-time), read-only): Completion time of a task.
  • doneBy (string, read-only): Who completed the task.
  • dueAt (string (date-time)): Due date of a task.
  • interactionId (string (uuid), read-only): The comms interaction a tracked call or meeting records.
  • leadId (string (uuid)): Lead the activity belongs to; omitted when not set.
  • opportunityId (string (uuid)): Opportunity the activity belongs to; omitted when not set.
  • recordName (string, read-only): Title of the opportunity, else company of the lead the activity belongs to; set by the activity list only.

Example 201 answer:

{
  "assigneeEmail": "lena.vogel@muster-it.example",
  "body": "Frau Gaßner wollte die Freigabe des Budgets mit dem Gesellschafter klären.",
  "bookedMinutes": 25,
  "createdAt": "2026-11-12T16:45:00Z",
  "createdBy": "lena.vogel@muster-it.example",
  "createdByName": "Lena Vogel",
  "customerNo": "99999",
  "dueAt": "2026-11-20T09:00:00Z",
  "id": "1d3f5b7d-9e1a-4c3d-8f5b-9a1c3e5b7d9f",
  "kind": "TASK",
  "leadId": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f",
  "meta": {},
  "opportunityId": "7d9f1b3d-5e7a-4c9b-8f1d-5c7e9a1b3d5f",
  "recordName": "WLAN Sudhaus und Lager",
  "subject": "Angebot WLAN Sudhaus nachfassen",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-12T16:45:00Z"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/crm/v1/activities/mail' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Guten Tag Frau Gaßner,\n\nwie besprochen erhalten Sie anbei unser Angebot AN-2026-0012.\n\nViele Grüße\nLena Vogel","leadId":"5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f","opportunityId":"7d9f1b3d-5e7a-4c9b-8f1d-5c7e9a1b3d5f","subject":"Ihr Angebot für das WLAN in Sudhaus und Lager","to":"eva.gassner@brauerei-gassner.example"}'

View as Markdown · Interactive reference · OpenAPI