> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leadlex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Email

> Send an email through the workspace's connected Gmail or Office 365 account

## Request

### Headers

```
Authorization: Bearer wbk_your_api_key_here
Content-Type: application/json
```

<ParamField header="Idempotency-Key" type="string">
  Optional client-generated key (UUIDv4 recommended). When present, the gateway deduplicates retries within a 24-hour window and returns the original response. Strongly recommended for all send operations so that network retries never produce duplicate messages.
</ParamField>

### Body Parameters

<ParamField body="to" type="string | array" required>
  Recipient email address, or an array of addresses. RFC 5322 addresses are accepted (e.g. `"Jane Doe <jane@example.com>"`).
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line. Maximum 998 characters per RFC 2822, but 150 characters is strongly recommended for deliverability.
</ParamField>

<ParamField body="body_html" type="string">
  HTML-formatted message body. Either `body_html` or `body_text` is required. When both are supplied, the email is sent as a multipart/alternative message and clients select the best representation.
</ParamField>

<ParamField body="body_text" type="string">
  Plain-text message body. Either `body_html` or `body_text` is required.
</ParamField>

<ParamField body="cc" type="array">
  Optional array of carbon-copy recipients.
</ParamField>

<ParamField body="bcc" type="array">
  Optional array of blind carbon-copy recipients.
</ParamField>

<ParamField body="reply_to" type="string">
  Optional Reply-To address. Defaults to the sending mailbox when omitted.
</ParamField>

<ParamField body="contact_id" type="string">
  Optional contact UUID. When supplied, the message is linked to the contact's timeline automatically.
</ParamField>

<ParamField body="deal_id" type="string">
  Optional deal UUID. When supplied, the message is logged against the deal.
</ParamField>

<ParamField body="thread_id" type="string">
  Optional thread identifier to reply into an existing conversation. When omitted, a new thread is created.
</ParamField>

<ParamField body="attachments" type="array">
  Optional array of attachments. Each entry accepts `filename`, `mime_type`, and either `content_base64` or `storage_path`.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Message ID assigned by the email provider</ResponseField>
    <ResponseField name="thread_id" type="string">Thread identifier</ResponseField>
    <ResponseField name="provider" type="string">`gmail` or `microsoft`</ResponseField>
    <ResponseField name="status" type="string">`queued`, `sent`, or `failed`</ResponseField>
    <ResponseField name="sent_at" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

Every response also carries standard rate-limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `X-Request-ID` for support traceability.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://data.leadlex.com/functions/v1/api-gateway/v1/email/send \
    -H "Authorization: Bearer wbk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 7e0b7c0e-5b2f-4b17-bf2a-4d7e7e33d9f1" \
    -d '{
      "to": "jane@example.com",
      "subject": "Follow-up on our meeting",
      "body_html": "<p>Hi Jane, thanks for meeting with us today.</p>",
      "contact_id": "123e4567-e89b-12d3-a456-426614174000"
    }'
  ```

  ```python Python theme={null}
  import requests, uuid

  API_KEY = "wbk_your_api_key_here"
  BASE_URL = "https://data.leadlex.com/functions/v1/api-gateway"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
      "Idempotency-Key": str(uuid.uuid4()),
  }

  payload = {
      "to": "jane@example.com",
      "subject": "Follow-up on our meeting",
      "body_html": "<p>Hi Jane, thanks for meeting with us today.</p>",
      "contact_id": "123e4567-e89b-12d3-a456-426614174000",
  }

  response = requests.post(f"{BASE_URL}/v1/email/send", headers=headers, json=payload)
  print(response.json()["data"]["id"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://data.leadlex.com/functions/v1/api-gateway/v1/email/send',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer wbk_your_api_key_here',
        'Content-Type': 'application/json',
        'Idempotency-Key': crypto.randomUUID(),
      },
      body: JSON.stringify({
        to: 'jane@example.com',
        subject: 'Follow-up on our meeting',
        body_html: '<p>Hi Jane, thanks for meeting with us today.</p>',
        contact_id: '123e4567-e89b-12d3-a456-426614174000',
      }),
    }
  );
  const { data } = await response.json();
  console.log(data.id);
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "data": {
    "id": "18c9a4b2e7ff21aa",
    "thread_id": "18c9a4b2e7ff21aa",
    "provider": "gmail",
    "status": "sent",
    "sent_at": "2026-04-17T10:22:11Z"
  }
}
```

## Errors

| Status | Code                       | Description                                                       |
| ------ | -------------------------- | ----------------------------------------------------------------- |
| 400    | `validation_error`         | Missing `to`, `subject`, or both `body_html` and `body_text`      |
| 401    | `invalid_key`              | Invalid or expired API key                                        |
| 403    | `insufficient_permissions` | Missing `write:email` permission, or no connected email provider  |
| 409    | `idempotency_conflict`     | Same `Idempotency-Key` reused with a different payload            |
| 429    | `rate_limited`             | Per-second or per-day send cap exceeded                           |
| 502    | `provider_error`           | The upstream email provider (Gmail / Microsoft) returned an error |