Send Email

Queue an email for background delivery from a verified sender address in the API key workspace. The API creates one tracked message per unique recipient and returns those message identifiers immediately.

Delivery Behavior

How queueing, normalization, and recipient tracking work

  • The endpoint returns 202 Accepted after messages are created and queued for delivery.
  • Provide either html or text; you can send both, but at least one is required.
  • Provide at least one recipient across to and bcc.
  • Recipient addresses are normalized and deduplicated case-insensitively. When the same address appears in both to and bcc, the to recipient wins.
  • Leadpush creates one tracked message per unique recipient, including BCC recipients.
  • If a recipient email matches an existing contact in the workspace, the message is linked to that contact automatically. Unknown recipients are sent without creating contacts.
  • Accepted messages start with status: "pending". Suppression checks, delivery failures, and final message states are handled asynchronously.

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

Verified sendable email address configured for the API key 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

Primary recipient email addresses. Required when `bcc` is not provided.

bccarray

Optional blind-copy recipients

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": {
  "accepted": true,
  "message_count": 4,
  "messages": [
    {
      "uuid": "<message_uuid>",
      "recipient": "known@example.test",
      "type": "to",
      "from": "sender@developer.test",
      "status": "pending"
    },
    {
      "uuid": "<message_uuid>",
      "recipient": "other@example.test",
      "type": "to",
      "from": "sender@developer.test",
      "status": "pending"
    },
    {
      "uuid": "<message_uuid>",
      "recipient": "third@example.test",
      "type": "to",
      "from": "sender@developer.test",
      "status": "pending"
    },
    {
      "uuid": "<message_uuid>",
      "recipient": "audit@example.test",
      "type": "bcc",
      "from": "sender@developer.test",
      "status": "pending"
    }
  ]
}
}

Validation Notes

Common request constraints to account for

  • The from address must be a verified sendable address in the API key workspace.
  • The endpoint requires SMTP access for the workspace owner. If the account does not have access, the API returns 403 with error: "upgrade_needed" and feature: "smtp.enabled".
  • The workspace owner email must be verified for sending. If verification is required, the API returns 403 with error: "email_verification_required".
  • headers must be an object of header names to string values, not an array.
  • Header names may only contain letters, numbers, and hyphens.
  • Header values may not contain line breaks.
  • Delivery headers such as From, To, Bcc, Reply-To, Subject, Message-ID, and Return-Path are reserved and cannot be overridden.
  • Custom X-Leadpush-* headers are reserved except X-Leadpush-Tag, which may be used to tag the resulting messages.
  • The response reports the actual sender used for each message. For known contacts with a configured delivery route, this can differ from the requested from address.

Need the setup path before sending? Start with Authorization, Create Domain Address, or SMTP Setup when you are migrating an existing mailer.