# Reminders

> Docs index: https://wahasend.com/llms.txt · Everything in one file: https://wahasend.com/docs.md · API base URL: https://app.wahasend.com/api/v1

A reminder is a message to one person at a set time, once or repeated daily, weekly or monthly (monthly keeps the day of the month; the 31st becomes the last day of shorter months). Checked every 30 seconds. Comes with **Notify** (feature `reminders`). Statuses: `scheduled`, `processing`, `done`, `failed`, `cancelled`.

<a id="reminder-list"></a>

### List reminders

`GET /api/v1/reminders`

Upcoming ones first (soonest first), then the others (latest change first).

- Unlocked by: Notify (`reminders`) + Developer or Connect for an API key
- Account key only

**Query parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | `scheduled`, `processing`, `done`, `failed` or `cancelled`. |
| `search` | string | no | Part of the phone number or label (100 characters max). |
| `page` | number | no | Default 1. |
| `limit` | number | no | Default 50, max 100. |

**Example**

curl:

```bash
curl "https://app.wahasend.com/api/v1/reminders?status=scheduled&limit=20" \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/reminders?status=scheduled&limit=20', {
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.get(
    "https://app.wahasend.com/api/v1/reminders?status=scheduled&limit=20",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "total": 1,
  "page": 1,
  "limit": 20,
  "reminders": [
    {
      "id": "a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28",
      "ownerId": "2c7d0e19-4b8a-4f63-9e21-7a5c3d9b1f08",
      "containerId": null,
      "label": "Rent — flat 3",
      "phone": "+22212345678",
      "message": "Hello {{name}}, your rent of {{amount}} is due tomorrow.",
      "variables": {
        "name": "Aïcha",
        "amount": "45 000 MRU"
      },
      "sendAt": "2026-11-01T09:00:00.000Z",
      "firstSendAt": "2026-10-01T09:00:00.000Z",
      "repeat": "monthly",
      "status": "scheduled",
      "batchId": null,
      "sendCount": 1,
      "lastSentAt": "2026-10-01T09:00:03.412Z",
      "lastMessageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
      "lastError": null,
      "createdAt": "2026-09-28T14:02:11.000Z",
      "updatedAt": "2026-10-01T09:00:03.500Z",
      "lastMessageStatus": "read"
    }
  ]
}
```

<a id="reminder-create"></a>

### Create a reminder

`POST /api/v1/reminders`

Schedules one message, optionally repeated. `{{variables}}` in the text are filled at send time.

- Unlocked by: Notify (`reminders`) + Developer or Connect for an API key
- Account key only

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | yes | International phone number; spaces, dashes, dots and brackets are removed. |
| `message` | string | yes | 1–4096 characters, may use `{{variables}}`. |
| `sendAt` | string (ISO 8601) | yes | First send time, with `Z` or an offset (`2026-10-01T09:00:00+00:00`). At most 5 minutes in the past. |
| `repeat` | "none" \| "daily" \| "weekly" \| "monthly" | no | Default `none`. |
| `label` | string \| null | no | Your own note, up to 255 characters. |
| `variables` | object (string → string) | no | Up to 50 values (keys ≤ 100, values ≤ 1000 characters). |
| `containerId` | uuid \| null | no | Number to send from; `null` = your default number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/reminders \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+22212345678",
  "message": "Hello {{name}}, your rent of {{amount}} is due tomorrow.",
  "sendAt": "2026-10-01T09:00:00Z",
  "repeat": "monthly",
  "label": "Rent — flat 3",
  "variables": {
    "name": "Aïcha",
    "amount": "45 000 MRU"
  }
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/reminders', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "phone": "+22212345678",
    "message": "Hello {{name}}, your rent of {{amount}} is due tomorrow.",
    "sendAt": "2026-10-01T09:00:00Z",
    "repeat": "monthly",
    "label": "Rent — flat 3",
    "variables": {
      "name": "Aïcha",
      "amount": "45 000 MRU"
    }
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/reminders",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "phone": "+22212345678",
        "message": "Hello {{name}}, your rent of {{amount}} is due tomorrow.",
        "sendAt": "2026-10-01T09:00:00Z",
        "repeat": "monthly",
        "label": "Rent — flat 3",
        "variables": {
            "name": "Aïcha",
            "amount": "45 000 MRU",
        },
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "reminder": {
    "id": "a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28",
    "phone": "+22212345678",
    "sendAt": "2026-10-01T09:00:00.000Z",
    "repeat": "monthly",
    "status": "scheduled",
    "…": "…"
  }
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NOT_FOUND`](https://wahasend.com/docs/errors.md#not_found) (404): Not found.

<a id="reminder-import"></a>

### Import many

`POST /api/v1/reminders/import`

One message template for up to 5000 rows (phone + time each). Rows in the past are skipped and listed, not refused.

- Unlocked by: Notify (`reminders`) + Developer or Connect for an API key
- Account key only

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | yes | 1–4096 characters, may use `{{variables}}`. |
| `repeat` | "none" \| "daily" \| "weekly" \| "monthly" | no | Default `none`. |
| `containerId` | uuid \| null | no | Number to send from. |
| `rows` | array | yes | 1–5000 rows. |
| `rows[].phone` | string | yes | International phone number, 8–20 characters (`+22212345678`). `@lid` ids are not accepted here. |
| `rows[].sendAt` | string (ISO 8601) | yes | With `Z` or an offset. |
| `rows[].label` | string \| null | no | Up to 255 characters. |
| `rows[].variables` | object (string → string) | no | Values for this row. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/reminders/import \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Hello {{name}}, see you at {{time}}.",
  "rows": [
    {
      "phone": "+22212345678",
      "sendAt": "2026-10-02T08:00:00Z",
      "variables": {
        "name": "Aïcha",
        "time": "10:00"
      }
    },
    {
      "phone": "+22287654321",
      "sendAt": "2026-10-02T08:00:00Z",
      "variables": {
        "name": "Moussa",
        "time": "11:30"
      }
    }
  ]
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/reminders/import', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "message": "Hello {{name}}, see you at {{time}}.",
    "rows": [
      {
        "phone": "+22212345678",
        "sendAt": "2026-10-02T08:00:00Z",
        "variables": {
          "name": "Aïcha",
          "time": "10:00"
        }
      },
      {
        "phone": "+22287654321",
        "sendAt": "2026-10-02T08:00:00Z",
        "variables": {
          "name": "Moussa",
          "time": "11:30"
        }
      }
    ]
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/reminders/import",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "message": "Hello {{name}}, see you at {{time}}.",
        "rows": [
            {
                "phone": "+22212345678",
                "sendAt": "2026-10-02T08:00:00Z",
                "variables": {
                    "name": "Aïcha",
                    "time": "10:00",
                },
            },
            {
                "phone": "+22287654321",
                "sendAt": "2026-10-02T08:00:00Z",
                "variables": {
                    "name": "Moussa",
                    "time": "11:30",
                },
            },
        ],
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "created": 2,
  "batchId": "e5c1a9f3-2d7b-4b8e-a6f0-8c3d1e5b9a72",
  "skipped": []
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NOT_FOUND`](https://wahasend.com/docs/errors.md#not_found) (404): Not found.

<a id="reminder-update"></a>

### Edit a reminder

`PUT /api/v1/reminders/:id`

Any field of create. A new `sendAt` re-arms a done, failed or cancelled reminder.

- Unlocked by: Notify (`reminders`) + Developer or Connect for an API key
- Account key only

**Path parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | Reminder id. |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | string | no | International phone number. |
| `message` | string | no | 1–4096 characters. |
| `sendAt` | string (ISO 8601) | no | New time; re-arms the reminder. |
| `repeat` | "none" \| "daily" \| "weekly" \| "monthly" | no | New repetition. |
| `label` | string \| null | no | Up to 255 characters. |
| `variables` | object (string → string) | no | Replaces the values. |
| `containerId` | uuid \| null | no | Number to send from. |

**Example**

curl:

```bash
curl -X PUT https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28 \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sendAt": "2026-10-03T09:00:00Z"
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28', {
  method: 'PUT',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "sendAt": "2026-10-03T09:00:00Z"
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.put(
    "https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "sendAt": "2026-10-03T09:00:00Z",
    },
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "reminder": {
    "id": "a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28",
    "sendAt": "2026-10-03T09:00:00.000Z",
    "status": "scheduled",
    "…": "…"
  }
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NOT_FOUND`](https://wahasend.com/docs/errors.md#not_found) (404): Not found.
- [`FORBIDDEN_ACTION`](https://wahasend.com/docs/errors.md#forbidden_action) (400): This action is not allowed.

<a id="reminder-cancel"></a>

### Cancel

`POST /api/v1/reminders/:id/cancel`

Stops a `scheduled` reminder (it stays in the list as `cancelled`).

- Unlocked by: Notify (`reminders`) + Developer or Connect for an API key
- Account key only

**Path parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | Reminder id. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28/cancel \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28/cancel', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28/cancel",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Response 200**

```json
{
  "success": true,
  "reminder": {
    "id": "a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28",
    "status": "cancelled",
    "…": "…"
  }
}
```

**Errors to expect**

- [`NOT_FOUND`](https://wahasend.com/docs/errors.md#not_found) (404): Not found.
- [`FORBIDDEN_ACTION`](https://wahasend.com/docs/errors.md#forbidden_action) (400): This action is not allowed.

<a id="reminder-delete"></a>

### Delete

`DELETE /api/v1/reminders/:id`

Removes the reminder for good.

- Unlocked by: Notify (`reminders`) + Developer or Connect for an API key
- Account key only

**Path parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | Reminder id. |

**Example**

curl:

```bash
curl -X DELETE https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28 \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.delete(
    "https://app.wahasend.com/api/v1/reminders/a7e3c5d1-9b2f-4e6a-8c04-5d1f3b7e9a28",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Response 200**

```json
{
  "success": true
}
```

**Errors to expect**

- [`NOT_FOUND`](https://wahasend.com/docs/errors.md#not_found) (404): Not found.