Send Email

Send individual or bulk transactional emails to one or more recipients. The sender address must belong to a verified domain on your project.

This endpoint requires a secret key (sk_*). Never expose your secret key in client-side code.

POST /v1/send

string | object | array

required

Recipient email address(es). Accepts three formats:

String: "[email protected]"
Object: { "name": "Jane Doe", "email": "[email protected]" }
Array: mix of strings and objects

Show Object properties

to.email

string

required

Recipient email address.

to.name

string

Recipient display name. Used to populate the {{name}} template variable automatically.

subject

string

Email subject line. Required unless a template is specified. Supports {{variable}} syntax.

body

string

HTML email body. Required unless a template is specified. Supports {{variable}} syntax.

template

string

ID of a saved template to use as the email’s subject, body, from address, and reply-to. You can override any of these by providing the corresponding field in the request.

from

string | object

Sender email address. Required unless the specified template already has a from address configured. The domain must be verified on your project.Accepts a plain email string or an object with name and email.

Show Object properties

from.email

string

required

Sender email address.

from.name

string

Sender display name.

name

string

Sender display name. Alternative to from.name — used when from is provided as a plain string.

string

Reply-to email address.

subscribed

boolean

default:"false"

Sets the recipient’s subscription status. Defaults to false for transactional emails, which means new contacts are created as unsubscribed. Set to true to opt them in to marketing emails.

headers

object

Custom email headers as key-value pairs. Values must be strings.

data

object

Template variables and contact data. Simple values ("key": "value") are saved to the contact record. To pass a value to the template without saving it to the contact, use the non-persistent format.

Show Non-persistent field format

{
  "success": true,
  "data": {
    "emails": [
      {
        "contact": {
          "id": "clx_contact_abc123",
          "email": "[email protected]"
        },
        "email": "clx_email_xyz789"
      }
    ],
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

POST /v1/verify

Validates an email address for deliverability. Checks for disposable domains, MX record existence, and common typos.

This endpoint requires a secret key (sk_*).

string

required

The email address to verify.

Response

success

boolean

true when the request succeeded.

data

object

Show properties

string

The email address that was verified.

valid

boolean

Whether the email appears to be valid and deliverable.

isDisposable

boolean

Whether the domain is a known disposable email provider.

hasMxRecords

boolean

Whether the domain has MX records configured.

suggestedEmail

string

Suggested correction if a typo was detected (e.g. [email protected] for [email protected]).

reasons

string[]

Human-readable descriptions of any issues found.

Example

curl --request POST \
  --url https://next-api.useplunk.com/v1/verify \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "[email protected]" }'

200

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "valid": false,
    "isDisposable": false,
    "hasMxRecords": false,
    "suggestedEmail": "[email protected]",
    "reasons": [
      "Possible typo detected, did you mean [email protected]?",
      "Domain does not exist or has no MX records"
    ]
  }
}

Non-persistent values are available in the template via {{orderId}} but are not stored on the contact.

System variables are automatically available in every template:

Variable	Description
`{{id}}`	Contact ID
`{{email}}`	Contact email
`{{unsubscribeUrl}}`	One-click unsubscribe link
`{{subscribeUrl}}`	Re-subscribe link
`{{manageUrl}}`	Subscription management page

Fallback syntax: use {{field ?? default}} to provide a default if the variable is missing.

attachments

array

Email attachments. Maximum 10 attachments, 10 MB total.

Show Attachment properties

attachments[].filename

string

required

Attachment filename (max 255 characters).

attachments[].content

string

required

Base64-encoded file content.

attachments[].contentType

string

required

MIME type, e.g. application/pdf, image/png (max 255 characters).

attachments[].disposition

string

default:"attachment"

Attachment disposition. attachment (default) adds it as a downloadable file. inline embeds it in the email body (requires contentId).

attachments[].contentId

string

Content ID for inline attachments. Required when disposition is inline. Used to reference the attachment in the HTML body via <img src="cid:yourContentId">.

Response

success

boolean

required

true when the request was accepted.

data

object

required

Show properties

emails

array

required

One entry per recipient.

Show Email entry properties

contact

object

Show properties

string

Contact ID.

string

Contact email address.

string

Email record ID.

timestamp

string

ISO 8601 timestamp when the request was processed.

Examples

curl --request POST \
  --url https://next-api.useplunk.com/v1/send \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "[email protected]",
    "from": {
      "name": "My App",
      "email": "[email protected]"
    },
    "subject": "Your password reset code",
    "body": "<h1>Reset your password</h1><p>Your code: <strong>{{resetCode}}</strong></p><p><a href=\"{{unsubscribeUrl}}\">Unsubscribe</a></p>",
    "data": {
      "resetCode": { "value": "ABC-123", "persistent": false }
    }
  }'

Example response

200

{
  "success": true,
  "data": {
    "emails": [
      {
        "contact": {
          "id": "clx_contact_abc123",
          "email": "[email protected]"
        },
        "email": "clx_email_xyz789"
      }
    ],
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Overview

Endpoints

POST /v1/send

POST /v1/verify

Response

Response

Examples

Example response

Build docs developers (and LLMs) love

Overview

Endpoints

​POST /v1/send

​POST /v1/verify

​Response

​Response

​Examples

​Example response

Build docs developers (and LLMs) love

POST /v1/send

POST /v1/verify

Response

Response

Examples

Example response