API Reference for Email Broadcast - Ensend Documentation

Initial Broadcast Batch
Subsequent Broadcast Batch

const ensend = new Client({
  secret: "your_project_secret",
});

const { data, error } = await ensend.SendApi.SendMailBroadcast({
  subject: "My Broadcast",
  sender: {
    name: "your_identity_name",
    address: "your_sender_identity"
  },
  recipients: [{
    name: "your_recipient_name",
    address: "your_recipient_address"
  }],
   message: "<b>It works 🎉</b>",
  // ...see additional fields below
});

import "github.com/express-labs/ensend-client-go"
client := ensend.New(option.WithProjectSecret("your_project_secret"))

curl -X POST 'https://api.ensend.co/send/mail/broadcast' \
  -H 'Authorization: Bearer <your_project_secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "My Broadcast",
    "sender": {
      "name": "your_identity_name",
      "address": "your_sender_identity"
    },
    "recipients": [{
      "name": "your_recipient_name",
      "address": "your_recipient_address"
    }],
    "message": "<b>It works 🎉</b>"
    # ...see additional fields below
  }'

Request Body

subject

string

required

The subject line of the email as it should appear in recipients’ inbox.

preheader

string (optional)

The text that appears below the subject line in notifications from inbox clients (like Gmail, Outlook, Apple Mail). This provides a second line for upselling and helps to increase open rates.

sender

object

required

Hide Child Attributes

name

string

The name of the sender as it should appear in recipients’ inbox.If a name is not provided, the username part of the sender address is used. Example: hello becomes the sender name for hello@ensend.co.

address

string

required

The email address of the sender as it should appear in recipients’ inbox.The sender address can any of the sender identities available to your project. Learn more about creating a sender identity.

message

string (optional if using template)

The body of the email as it should appear in recipients’ inbox. This can either be in plaintext or html format.

template

object (optional if using message)

Hide Child Attributes

ref

string

required

This is a reference to any email template available in your project.You can only obtain a ref after creating an email template in your project. Learn more about creating a template.

variables

object (optional)

A key-value pair that assign values to template variables. These variable are treated as global variables and are applied to every message.When variables are specified for each recipient, these are treated as a fallback values.

// Example
{
	"displayPhoto": "https://link-to-avatar.png",
	"citizenship": "Global Citizen"
}

recipients

object[] (optional if using sources)

This is the list of users the broadcast will be delivered to. Recipients can be added in batches, limited to 250 recipients per batch.If you’re avoiding sending in batches, check out adding a recipient source to a broadcast.

Hide Child Attributes

name

string

This is the name of the recipient as it will in your audience list. This name is also used when deriving traits like {{profile.firstName}} , so you want to ensure it is accurate.If a name is not provided, the username part of the recipient address is used.
Example: tenotea becomes the recipient name for tenotea@ensend.co.

address

string

The email address of the recipient the broadcast message will be delivered to. This can be any email address which you have received explicit permission to send an email to.

variables

object

A key-value pair that assign values to template variables. These variables override global variables and are applied only the corresponding recipient, unlocking message personalization at scale.

// Example
{
	"displayPhoto": "https://link-to-profile-picture.png",
	"citizenship": "Brazilian Citizen"
}

sources

object[] (optional if using recipients)

Sources point to pre-existing list of users. This unlocks sending a broadcast to thousands of recipients with a single . Audience groups and CSV files are supported as of today. More source options will be added to aid in building custom and flexible broadcast pipelines.

Audience Groups
CSV File

Hide Child Attributes

ref

string

required

Enter a description

actionOnExistingTrait

preserve | override

Enter a description

actionOnExistingProfile

preserve | override

Enter a description

includeUnsubscribed

boolean

Enter a description

replyAddress

string

Enter a description

attachments

object[]

Hide Child Attributes

name

string

Enter a description

url

string (optional if using content)

Enter a description

content

string (optional if using url)

Enter a description

options

object

Hide Child Attributes

acquiringAudience

string

Enter a description

scheduleFor

Date

Enter a description

storeContent

boolean

whether the rendered email content is retained on the backend after sending — useful for audit trails and resending, but worth turning off for highly sensitive one-off content you don’t want persisted.

const ensend = new Client({
  secret: "your_project_secret",
});

const { data, error } = await ensend.SendApi.SendExistingMailBroadcast({
  broadcastRef: "your_broadcast_ref",
  recipients: [{
    name: "your_recipient_name",
    address: "your_recipient_address"
  }]
});

Request Body

broadcastRef

string

required

This is the reference to a broadcast that has already been created. You can obtain your broadcastRef by sending an initial broadcast batch or copying the ref from your project dashboard.

recipients

object[] (optional if using sources)

Hide Child Attributes

name

string

address

string

The email address of the recipient the broadcast message will be delivered to. This can be any email address which you have received explicit permission to send an email to.

variables

object

A key-value pair that assign values to template variables. These variables override global variables and are applied only the corresponding recipient, unlocking message personalization at scale.

// Example
{
	"displayPhoto": "https://link-to-profile-picture.png",
	"citizenship": "Brazilian Citizen"
}

​Request Body

​Request Body

Request Body

Request Body