REST API

API Reference

Send transactional and campaign emails, manage mailboxes, and configure sender groups — all from your application.

Your API Key — paste it here to auto-fill all examples and try requests live

Your key is never sent to our servers from this page — requests go directly to the API. Get your API key →

Overview

The RemindMe API is a simple HTTP REST API. All endpoints are hosted at:

https://api.remindme.me

Format

JSON request and response bodies.

Auth

Bearer token via the Authorization header.

Errors

Standard HTTP status codes with an error field in the body.

SDK

Use the remindme npm package for a typed client.

Error responses

All errors return a JSON body with an error field:

HTTP 401
{
  "error": "Invalid or revoked API key"
}

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer dm_live_your_api_key_here

Go to the Developer section in your dashboard.

Click Create API Key, give it a name, and select the domain it should be scoped to.

Copy the key immediately — it is shown only once and stored as a hash.

Each API key is scoped to a single verified domain. The key can only access mailboxes and sender groups on that domain.

Quick start

curl -X GET https://api.remindme.me/v1/mailboxes \
  -H "Authorization: Bearer dm_live_your_key"

GET/v1/mailboxes

List Mailboxes

Returns all mailboxes that belong to the domain scoped to your API key. Each mailbox includes its local address, full address, and optional display name.

Returns: Array of Mailbox objects.

curl -X GET https://api.remindme.me/v1/mailboxes \
  -H "Authorization: Bearer dm_live_..."

Try it

POST/v1/mailboxes

Create Mailbox

Creates a new mailbox on the domain associated with your API key. Only the local part of the address is needed (e.g. 'hello' — the domain suffix is appended automatically).

Returns 409 if the mailbox already exists.

Parameters

Name	Type	Description
`address`	text*	The local part of the email address, e.g. hello (not hello@domain.com).
`displayName`	text	Optional sender display name, e.g. 'Support Team'.

* required

Returns: The created Mailbox object.

curl -X POST https://api.remindme.me/v1/mailboxes \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"address":"hello","displayName":"Hello Team"}'

Try it

Address (local part) *

The local part of the email address, e.g. hello (not hello@domain.com).

Display Name

Optional sender display name, e.g. 'Support Team'.

DELETE/v1/mailboxes/:address

Delete Mailbox

Permanently deletes a mailbox and all its emails. Also removes it from any sender groups it belongs to. Pass the local part ('hello') or the full address ('hello@domain.com').

This action is irreversible. All emails in the mailbox are permanently deleted.

Parameters

Name	Type	Description
`address`path	text*	Local part or full address of the mailbox to delete.

* required

Returns: { deleted: true }

curl -X DELETE https://api.remindme.me/v1/mailboxes/hello \
  -H "Authorization: Bearer dm_live_..."

Try it

Address *path param

Local part or full address of the mailbox to delete.

GET/v1/sender-groups

List Sender Groups

Returns all sender groups for the API key's domain. A sender group defines which mailboxes act as senders and which recipient emails are targeted.

Returns: Array of SenderGroup objects.

curl -X GET https://api.remindme.me/v1/sender-groups \
  -H "Authorization: Bearer dm_live_..."

Try it

POST/v1/sender-groups

Create Sender Group

Creates a sender group. Specify which sender mailboxes to include and an optional list of recipient emails. Pass 'all' for mailboxes to include every mailbox on the domain.

Parameters

Name	Type	Description
`name`	text*	A descriptive name for the group.
`mailboxes`	text	Comma-separated mailbox addresses to include as senders, or "all" to include every mailbox on the domain. Defaults to "all".
`emails`	csv	Comma or newline separated list of recipient email addresses.

* required

Returns: The created SenderGroup object.

curl -X POST https://api.remindme.me/v1/sender-groups \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My Group","mailboxes":"all","emails":[]}'

Try it

Group Name *

A descriptive name for the group.

Sender Mailboxes

Comma-separated mailbox addresses to include as senders, or "all" to include every mailbox on the domain. Defaults to "all".

Recipient Emails

Comma or newline separated list of recipient email addresses.

PATCH/v1/sender-groups/:id

Update Sender Group

Updates a sender group. All fields are optional — only the fields you provide will be changed. Use addEmails / removeEmails for incremental recipient list changes, or emails to replace the entire list at once.

Parameters

Name	Type	Description
`id`path	text*	The ID of the sender group to update (from listSenderGroups).
`name`	text	New name for the group.
`addEmails`	csv	Emails to add to the recipient list.
`removeEmails`	csv	Emails to remove from the recipient list.
`emails`	csv	Replace the entire recipient list with this set. Overrides addEmails/removeEmails.
`mailboxes`	text	Replace the sender mailbox list. Comma-separated addresses or "all".

* required

Returns: The updated SenderGroup object.

curl -X PATCH https://api.remindme.me/v1/sender-groups/GROUP_ID \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Try it

Group ID *path param

The ID of the sender group to update (from listSenderGroups).

Name

New name for the group.

Add Emails

Emails to add to the recipient list.

Remove Emails

Emails to remove from the recipient list.

Replace All Emails

Replace the entire recipient list with this set. Overrides addEmails/removeEmails.

Sender Mailboxes

Replace the sender mailbox list. Comma-separated addresses or "all".

DELETE/v1/sender-groups/:id

Delete Sender Group

Permanently deletes a sender group. The mailboxes themselves are not affected.

Parameters

Name	Type	Description
`id`path	text*	The ID of the sender group to delete.

* required

Returns: { deleted: true }

curl -X DELETE https://api.remindme.me/v1/sender-groups/GROUP_ID \
  -H "Authorization: Bearer dm_live_..."

Try it

Group ID *path param

The ID of the sender group to delete.

POST/v1/send

Send Email

Sends an email from a mailbox on the API key's domain. Supports transactional sends (one email to all recipients), campaign sends (individual email per recipient with a shared batchId), and scheduled sends (delivered at a future time).

The from address must be an existing mailbox created under this API key's domain.
For campaign sends, each recipient receives a separate individually tracked email.
scheduledAt must be a future unix millisecond timestamp.

Parameters

Name	Type	Description
`from`	text*	Full address of the sender mailbox. Must be an existing mailbox on your domain.
`to`	csv*	One or more recipient email addresses (comma or newline separated).
`subject`	text*	Email subject line.
`html`	textarea	HTML content of the email. Either html or text is required.
`text`	textarea	Plain text fallback. Used if html is not provided.
`type`	select	"transactional" sends one email to all recipients together. "campaign" sends individual emails to each recipient, all tracked under a shared batchId.
`scheduledAt`	datetime	Schedule the email for a future time. Leave blank to send immediately.

* required

Returns: For transactional: { messageId, status }. For campaign: { messageIds, batchId, status }. status is 'queued' or 'scheduled'.

curl -X POST https://api.remindme.me/v1/send \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "hello@yourdomain.com",
  "to": [
    "user@example.com"
  ],
  "subject": "Hello!"
}'

Try it

From *

Full address of the sender mailbox. Must be an existing mailbox on your domain.

To *

One or more recipient email addresses (comma or newline separated).

Subject *

Email subject line.

HTML Body

HTML content of the email. Either html or text is required.

Plain Text Body

Plain text fallback. Used if html is not provided.

Send Type

"transactional" sends one email to all recipients together. "campaign" sends individual emails to each recipient, all tracked under a shared batchId.

Schedule At

Schedule the email for a future time. Leave blank to send immediately.

Node.js SDK

Install the official typed SDK to avoid writing raw fetch calls:

npm install remindme-sdk\n# or\nbun add remindme-sdk

import { RemindMe } from 'remindme-sdk';

const client = new RemindMe('dm_live_your_key');

// List mailboxes
const mailboxes = await client.listMailboxes();

// Send an email
const result = await client.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Hello!',
  html: '<p>Sent via RemindMe.</p>',
});

// Campaign send
const campaign = await client.send({
  from: 'hello@yourdomain.com',
  to: ['a@example.com', 'b@example.com'],
  subject: 'Big announcement',
  html: '<h1>Hello!</h1>',
  type: 'campaign',
});

// Scheduled send
const scheduled = await client.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Reminder',
  html: '<p>This is scheduled.</p>',
  scheduledAt: Date.now() + 60 * 60 * 1000, // 1 hour from now
});