Emails

Send email and query delivery status.

POST/v1/emails/send

Send an email

Requires the emails:send permission and a verified from domain.

Body

Parameter	Description
`from` stringrequired	Sender address on a verified domain.
`to` string \| string[]required	Recipient(s).
`subject` stringrequired	Up to 998 characters.
`html` string	HTML body.
`text` string	Plain-text body.
`cc / bcc` string \| string[]	Carbon/blind-carbon copy recipients.
`reply_to` string	Reply-To address.
`tags` Record<string, string>	Custom key/value metadata.
`attachments` Attachment[]	Up to 20 files, 40 MB per message after base64 encoding.

Attachment object

Parameter	Description
`filename` stringrequired	Name the recipient sees. Optional with path, where the URL filename is used.
`content` string (base64)	File contents. The SDK accepts a Buffer/Blob/File and encodes it. Mutually exclusive with path.
`path` string	Public https URL to download the file from. Mutually exclusive with content.
`content_type` string	MIME type. Inferred from the filename when omitted.
`content_id` string	Makes the part inline for cid: references in HTML.

Request

cURL

curl -X POST https://api.cmdsend.com/v1/emails/send \
  -H "Authorization: Bearer cmd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>Hi there!</p>"
  }'

Node.js (cmdsend SDK)

import { Cmdsend } from 'cmdsend';
const cmdsend = new Cmdsend('cmd_your_api_key');

const result = await cmdsend.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hi there!</p>',
});

With an attachment

import { readFile } from 'node:fs/promises';

await cmdsend.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your invoice',
  html: '<p>Invoice attached.</p>',
  attachments: [
    { filename: 'invoice.pdf', content: await readFile('./invoice.pdf') },
  ],
});

Response 202

The send is accepted and queued for scanning before delivery.

{
  "id": "a1b2c3d4-...",
  "status": "queued",
  "created_at": "2026-08-01T12:00:00.000Z",
  "recipients": 1,
  "attachments": 1
}

GET/v1/emails/:id

Retrieve an email

Returns the current status and full event timeline for one send. Requires emails:read.

Request

cURL

curl https://api.cmdsend.com/v1/emails/a1b2c3d4-... \
  -H "Authorization: Bearer cmd_your_api_key"

Response 200

{
  "id": "a1b2c3d4-...",
  "from_email": "hello@yourdomain.com",
  "to_email": "user@example.com",
  "subject": "Hello",
  "status": "delivered",
  "ses_message_id": "0100019...",
  "created_at": "2026-08-01T12:00:00.000Z",
  "sent_at": "2026-08-01T12:00:01.000Z",
  "delivered_at": "2026-08-01T12:00:03.000Z",
  "opened_at": null,
  "clicked_at": null,
  "bounced_at": null,
  "events": [
    {
      "event_type": "sent",
      "metadata": {},
      "occurred_at": "2026-08-01T12:00:01.000Z"
    },
    {
      "event_type": "delivered",
      "metadata": {},
      "occurred_at": "2026-08-01T12:00:03.000Z"
    }
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "content_id": null,
      "size_bytes": 24518
    }
  ]
}

GET/v1/emails

List emails

Paginated, filterable list of your sends.

Query parameters

Parameter	Description
`page` number	Default 1.
`per_page` number	Default 20, max 100.
`status` string	Filter by delivery status.
`to` string	Filter by recipient (partial match).
`date_from / date_to` string (ISO date)	Filter by created date range.

Request

cURL

curl "https://api.cmdsend.com/v1/emails?status=delivered&per_page=10" \
  -H "Authorization: Bearer cmd_your_api_key"

Response 200

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "from_email": "hello@yourdomain.com",
      "to_email": "user@example.com",
      "subject": "Hello",
      "status": "delivered",
      "attachment_count": 1,
      "created_at": "2026-08-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "total_pages": 1
  }
}