Send Email

Queue an email for background delivery from a sendable workspace address. The API returns a send group identifier and the final recipient counts after normalization.

Delivery Behavior

How sending, normalization, and recipient linking work

  • The endpoint returns 202 Accepted after the email send is created and queued for delivery.
  • Provide either html or text; you can send both, but at least one is required.
  • Recipient addresses are normalized and deduplicated. Any address present in to is removed from bcc.
  • The final combined to and bcc recipient count may not exceed 50.
  • If a recipient email matches an existing contact in the workspace, the resulting message is linked to that contact automatically.
POST
/v1/workspaces/:workspace/emails

Queue a developer email send

Path parameters

workspacestring Required

ID of your workspace

Request body

fromstring Required

Sendable email address configured for the workspace

subjectstring Required

Email subject line

htmlstring

HTML email body. Required when `text` is not provided.

textstring

Plain text email body. Required when `html` is not provided.

toarray Required

Primary recipient email addresses. At least one recipient is required.

bccarray

Optional blind-copy recipients. Final unique `to` plus `bcc` count cannot exceed 50.

reply_tostring

Optional reply-to email address

headersobject

Optional custom email headers

Send Email
curl -X POST https://api.leadpush.io/v1/workspaces/:workspace/emails \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "from": "sender@developer.test",
  "subject": "Developer API email",
  "html": "<p>Hello world</p>",
  "text": "Hello world",
  "to": [
    "known@example.test",
    "other@example.test",
    "third@example.test"
  ],
  "bcc": [
    "audit@example.test"
  ],
  "reply_to": "reply@example.test",
  "headers": {
    "X-Correlation-ID": "abc-123",
    "Auto-Submitted": "auto-generated"
  }
}'
Response Example
{
"data": {
  "send_group_id": "<send_group_uuid>",
  "to_count": 3,
  "bcc_count": 1,
  "total_recipient_count": 4
}
}

Validation Notes

Common request constraints to account for

  • The from address must belong to a sendable address configured in the workspace.
  • headers must be an object of header names to string values, not an array.
  • Header names may only contain letters, numbers, and hyphens.
  • Header names and values may not contain line breaks.
  • The X-LEADPUSH-SEND-ID header is reserved and cannot be overridden.