Sending Emails

Send a Single Email

POST /api/v1/emails

Scope: emails:send

Request Body

Field	Type	Required	Description
`from`	string	Yes	Sender email (must match verified domain)
`to`	string \| string[]	Yes	Recipient(s), max 50
`subject`	string	Yes	Subject line, max 998 chars
`html`	string	No	HTML body
`text`	string	No	Plain text body
`cc`	string \| string[]	No	CC recipients
`bcc`	string \| string[]	No	BCC recipients
`replyTo`	string \| string[]	No	Reply-To address(es)
`headers`	object	No	Custom email headers
`attachments`	array	No	File attachments, max 20
`tags`	object	No	Key-value tags for tracking
`scheduledAt`	string	No	ISO 8601 date for delayed sending
`templateId`	string	No	Template ID to use
`variables`	object	No	Template variable values

Attachments

Each attachment has:

Field	Type	Required	Description
`filename`	string	Yes	File name
`content`	string	Yes	Base64-encoded content
`contentType`	string	No	MIME type (auto-detected if omitted)

Example

const { id } = await wm.emails.send({
  from: 'notifications@wistfare.com',
  to: ['user@example.com'],
  subject: 'Your order has shipped',
  html: `
    <h1>Order Shipped!</h1>
    <p>Your order #1234 is on its way.</p>
  `,
  tags: { orderId: '1234', type: 'shipping' },
})

Response

{ "id": "eml_a1b2c3d4e5f6..." }

Batch Send

POST /api/v1/emails/batch

Scope: emails:send

Send up to 100 emails in a single request.

const { ids } = await wm.emails.batchSend([
  {
    from: 'hello@wistfare.com',
    to: 'alice@example.com',
    subject: 'Welcome, Alice!',
    html: '<p>Welcome!</p>',
  },
  {
    from: 'hello@wistfare.com',
    to: 'bob@example.com',
    subject: 'Welcome, Bob!',
    html: '<p>Welcome!</p>',
  },
])
 
console.log(ids) // ['eml_xxx', 'eml_yyy']

Get Email Status

GET /api/v1/emails/:id

Scope: emails:read

const email = await wm.emails.get('eml_abc123')
console.log(email.status) // 'delivered' | 'bounced' | 'sent' | ...

Response

{
  "id": "eml_abc123",
  "status": "delivered",
  "from": "hello@wistfare.com",
  "to": ["user@example.com"],
  "subject": "Welcome!",
  "createdAt": "2026-03-28T12:00:00Z",
  "deliveredAt": "2026-03-28T12:00:01Z",
  "openedAt": "2026-03-28T14:30:00Z",
  "clickedAt": null,
  "bouncedAt": null
}

Email Statuses

Status	Description
`queued`	Email accepted, waiting to be sent
`sending`	Being processed by mail engine
`sent`	Handed off to recipient's mail server
`delivered`	Confirmed delivered to inbox
`bounced`	Delivery failed (hard or soft bounce)
`failed`	Sending error
`complained`	Recipient marked as spam

Cancel Scheduled Email

PATCH /api/v1/emails/:id/cancel

Cancel an email that was scheduled for future delivery.

await wm.emails.cancel('eml_abc123')

On this page