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 for a particular project defined by the API key used.

This call can have a user-supplied uid identifier used to make changes or to later delete the scheduled event. The uid value is an arbitrary string and will default to a server-generated UUID value if not specified.

The metadata payload is an arbitrary PostageApp send_message request. The project’s API key will be merged in automatically and can be omitted.

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 Structure

{
  "api_key" : "__PROJECT_API__KEY__",
  "uid": "__UID__",
  "schedule": "every 5 mins",
  "metadata": {
    "arguments": {
      "recipients": "test@example.com",
      "headers": {
        "from": "test@example.com",
        "subject": "Example Scheduled Email"
      },
      "content": {
        "text/plain": "This email was sent automatically."
      },
      "attachments": {
        "test.pdf": {
          "content_type": "application/octet-stream",
          "content": {
            "$ref": "http://example.com/resources/example.pdf", 
            "$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",
    "scheduled_at":"2018-12-18T18:10:00+00:00"
  }
}

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.