Schedules an API call to be made at one or more points in time in the future depending on the format of the schedule parameter provided the same project as the API key used to make this call.

The schedule parameter is very flexible, but must take one of the following forms to be interpreted correctly:

  • An ISO-8601 formatted date or date-time string (e.g. YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in 24-hour UTC time)
  • An expression of the form "in 5 minutes" where intervals supported are minutes, hours, days and months.
  • A date expression like "5 days from now" or "tomorrow"
  • A crontab-compatible specification like 0 * * * * (every hour at 0 on the hour) or 0 0 * * * (every day at midnight). This also includes directives like @hourly or @monthly.
  • A repeating expression like "every 3 hours" or "every day at 1am"

In all cases times are UTC.

Request Fields

These are passed in at the top level of the request.

Key Type Description
uid string
A user-specified identifier to refer to this scheduled event on subsequent API calls.
Default: Generated UUID
schedule string Defines the schedule to follow when sending this batch. Must conform to one of the supported schedule formats.
metadata object The send_message payload to process at the time of scheduled execution. The project’s API key will be merged in automatically and can be omitted.

Request Example

  "api_key" : "__PROJECT_API__KEY__",
  "uid": "__UID__",
  "schedule": "every 5 mins",
  "metadata": {
    "arguments": {
      "recipients": "",
      "headers": {
        "from": "",
        "subject": "Example Scheduled Email"
      "content": {
        "text/plain": "This email was sent automatically."
      "attachments": {
        "test.pdf": {
          "content_type": "application/octet-stream",
          "content": {
            "$ref": "", 
            "$type": "application/octet-stream",
            "$encode": "base64"

Response 200 OK

Upon successful creation a response of the following form is sent:

  "response" : {
    "status" : "ok",
    "uid" : "__UID__"
  "data" : {
    "uid": "__UID__",
    "status": "activated",
    "frequency": "every 5 mins",
    "event_type": "repeatable",

The scheduled_at field shows the execution time (UTC) of the event.

Response 400 Bad Request

If the UID is taken an error of the following form will be returned:

  "response": {
    "status": "bad_request",
    "uid": "__UID__",
    "message": "Could not create scheduled event."
  "data": {
    "errors": [
      "[:uid, :project id] is already taken"

Each UID value must be unique per-project. Existing events can be updated with the update_scheduled_event endpoint.