# Schedule email to list

**Summary:** Schedule an email to a list for a later time. Set scheduledAt as an ISO 8601 datetime and optionally a timeZone; without a timeZone the time is treated as UTC.

- Space: [Developers](https://www.subrite.no/developers)
- Source: https://www.subrite.no/developers/email-schedule
- Updated: 2026-09-23
- Markdown index: https://www.subrite.no/developers/llms.txt

Schedule an email to a list through Subrite.

- **Method:** `POST`
- **Route:** `{baseUrl}/api/v1/communications/email/schedule`
- **Authorization:** Bearer token (use the M2M token from [Setup](https://www.subrite.no/developers/email-setup?md=true))
- **Body:** see the example below

<a id="example-body"></a>
## Example body

```javascript
{
  "communicationType": "marketing",  // Possible values: "marketing" or "information"
  "name": "sample name",
  "senderId": 2,  // Use sender ID from Step 2 response
  "consentId": null,
  "segmentId": 1,  // Use segment ID from Step 3 response
  "subject": "email subject",
  "emailPreviewText": "sample",
  "emailContent": "<div>hello world</div>",
  "scheduledAt": "2025-03-26T05:14:25.064Z", // Set norway time
  "timeZone": "Europe/Oslo", // Optional: If not provided, UTC will be used
  "hostName": "example.com" // Optional. See "Host name" below.
}
```

In the example, the `senderId` comes from the step 2 response and the `segmentId` from the step 3 response on the [Setup](https://www.subrite.no/developers/email-setup?md=true) page.

<a id="host-name"></a>
## Host name

`hostName` is optional. When set, unsubscribe links generated for this email use the supplied hostname instead of the tenant's primary hostname. Use it when your tenant serves multiple brand domains so recipients land on the correct brand.

- Must match the tenant's primary hostname or one of its registered additional hostnames. Foreign or unregistered hostnames are silently ignored and the tenant's primary hostname is used as a fallback.
- DNS-safe characters only (`a-z`, `0-9`, `.`, `-`, optional `:port`); IDN hostnames must be supplied in punycode form.
- Omit the field to use the tenant's primary hostname.

<a id="success-response"></a>
## Success response

```javascript
{
  success: true,
  message: 'Test emails sent successfully',
  id: 8987
}
```

<a id="scheduling-time"></a>
## Scheduling time

The `scheduledAt` field expects:

- ISO 8601 datetime format
- UTC timezone (for example `2025-03-26T05:14:25.064Z`)
- If `timeZone` is not provided, the system will treat the time as UTC
- If `timeZone` is provided, the system will convert the time from the specified timezone to UTC

<a id="timezone-support"></a>
## Timezone support

The `timeZone` field accepts any valid IANA timezone string supported by the date-fns-tz library. Common examples include:

- `UTC`
- `Europe/Oslo`
- `Europe/London`
- `Europe/Paris`
- `Europe/Berlin`
- `America/New_York`
- `America/Los_Angeles`
- `Asia/Tokyo`
- `Asia/Shanghai`
- `Australia/Sydney`
- `Pacific/Auckland`

For a complete list of supported timezones, refer to the [IANA Time Zone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

Example:

```json
{
  "scheduledAt": "2025-03-26T05:14:25.064Z",
  "timeZone": "Europe/Oslo"
}
```

> [!NOTE]
> **Note**
>
> If you specify 05:14 UTC, it will be executed at:
>
> - 06:14 during winter time (UTC+1)
> - 07:14 during summer time (UTC+2)