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.

Use this endpoint for transactional email API sends such as password resets, OTPs, receipts, account alerts, and product notifications. For product-level capabilities and delivery visibility, see Transactional Email API & SMTP Relay.

POST
/v1/emails

Queue a developer email send

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/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.

Need the setup path before sending? Start with Authorization for API keys or SMTP Setup when you are migrating an existing mailer.