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):fieldnames the first invalid field,details.fieldsevery 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;
codesays 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 (subjectcrm:activity:<id>, worked minus breaks, ADR 0040); filled byGET /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):SYSTEMentries are history written by the CRM and cannot be created or changed. (one ofNOTE,CALL,MEETING,EMAIL,TASK,SYSTEM)meta(object, required): Details ofSYSTEMentries (for example the old and new stage); of a tracked interactioninteractionId,provider,summaryandtranscript(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"}'