Skip to main content

Schedule recipient APIs

The schedule recipient APIs allow you to manage and interact with recipients of schedules within your Omni organization.

List schedule recipients​

Retrieves the list of recipients for the specified schedule. Successful responses will include the recipients and details about the schedule's destination type.

To retrieve a schedule's full configuration, use the List schedules endpoint.

GET /api/v1/schedules/:scheduleId/recipients
curl -L 'https://myorg.omniapp.co/api/v1/schedules/e12c43d7-5989-42d5-bad7-f8a4a0aa8be2/recipients' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

Parameters​

Loading parameters...

Response​

200 OK

Successful requests will return a 200 OK status and response body specific to the schedule's destination type:

Email destinations​

Email destinations
{
    "recipients": [
        {
            "email": "blobby@blobsrus.com",
            "emailOnly": false,
            "id": "3e7c4152-cdac-42ce-8749-fe3b81d5d8ab",
            "name": "blobby@blobsrus.com"
        }
    ],
    "type": "email"
}

SFTP destinations​

SFTP destinations
{
  "type": "sftp",
  "address": "sftp.example.com",
  "port": 22,
  "username": "username"
}

Slack destinations​

Responses for schedules with Slack destinations will list channel or user recipients:

Channel recipients​
Slack destination with channel recipients
{
  "type": "slack",
  "recipients": [
    {
      "recipientType": "channel",
      "slackId": "C123456789"
    }
  ]
}
User recipients​
Slack destination with user recipients
{
  "type": "slack",
  "recipients": [
    {
      "recipientType": "users",
      "slackId": "U123456789"
    }
  ]
}

Webhook destinations​

Webhook destinations
{
  "type": "webhook",
  "url": "https://example.com/webhook"
}
400 Bad Request

Response bodies will be an object similar to the following:

{
    "detail": "<errorReason>",
    "status": 400
}
IssueError detail
Invalid UUID formatBad Request: scheduleId: Invalid uuid
Invalid methodInvalid method
404 Not Found
{
  "detail": "<errorReason>",
  "status": 404
}
ErrorError detail
Schedule not foundScheduled task with id {scheduleId} does not exist
429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Add recipients to email schedule​

Adds one or more recipients to an existing scheduled email task. Recipients can be specified by email address or user ID.

Limitations​

This API only works with schedules with email destinations.

PUT /api/v1/schedules/:scheduleId/add-recipients
curl -L -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/add-recipients' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "emails": ["user@example.com"]
}'

Parameters​

Loading parameters...

Response​

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "addedRecipientsCount": 2,
  "success": true
}
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
ErrorError detail
Invalid UUID formatuserIds: Invalid uuid
Invalid email formatemails: Invalid email address
Empty request bodyPlease provide either valid email addresses, valid user IDs, or both
No recipients provided- At least one recipient must be provided
- {parameter}: Array must contain at least 1 element(s)
Invalid membersInvalid recipient(s): The following members do not exist or do not have access to this organization: {userId}
Unsupported destination typeCannot add recipients to destination type {destinationType}
404 Not Found
{
  "detail": "<errorReason>",
  "status": 404
}
ErrorError detail
Schedule not foundScheduled task with id {scheduleId} does not exist
429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Remove recipients from email schedule​

Removes one or more recipients from an existing scheduled email task. Recipients can be specified by email address or user ID.

Limitations​

This API only works with schedules with email destinations.

PUT /api/v1/schedules/:scheduleId/remove-recipients
curl -L -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/remove-recipients' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "emails": ["user@example.com"]
}'

Parameters​

Loading parameters...

Response​

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "removedRecipientsCount": 2,
  "success": true
}
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
ErrorError detail
Invalid UUID formatBad Request: userIds: Invalid uuid
Invalid email formatBad Request: emails: Invalid email address
Empty request bodyPlease provide either valid email addresses, valid user IDs, or both
No recipients provided- At least one recipient must be provided
- {parameter}: Array must contain at least 1 element(s)
Invalid membersInvalid recipient(s): The following members do not exist or do not have access to this organization: {userId}
Unsupported destination typeCannot change recipients on a scheduled task destination of type {destinationType}
404 Not Found
{
  "detail": "<errorReason>",
  "status": 404
}
ErrorError detail
Schedule not foundScheduled task with id {scheduleId} does not exist
429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Create or update an email-only user​

Creates or updates an email-only user. An email-only user is a recipient of a delivery that isn't associated with an Omni account.

If Omni matches the provided email to an existing email-only user, the user will be updated according to the userAttributes in the request body.

tip

Need to include multiple email-only users? Use the Create or update multiple email-only users endpoint.

POST /api/v1/users/email-only
curl -X POST'https://myorg.omniapp.co/api/v1/users/email-only' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer <TOKEN>' \
--data '{
    "email": "iamagoodblob@myorg.co"
}'

Parameters​

Loading parameters...

Response​

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

200 OK
 {
    "email": "iamagoodblob@myorg.co",
    "userId": "9e8719d9-276a-4964-9395-a493189a247c"
}
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
ErrorError detail
Invalid JSON in request bodyInvalid JSON
Missing email parameteremail: email is required
email value isn't a valid email addressemail: Invalid email address
User attribute does not existThe provided user attributes: \"<attribute>\" do not match the names of existing user attributes.
User attribute type mismatchUser Attribute <attribute> is type number, but passed-in value <value> is not a number.
Invalid omni_user_timezone valueThe timezone <invalidTimezone> is not supported. Please see the connection page or user profile page for the list of valid timezones. Use e.g. \"America/New_York\" instead of \"EST\"
Multiple values not provided as arrayUser Attribute <attribute> has multiple values enabled, but the passed-in value is not an array. If passing a single value for a user attribute with multiple values enabled, please wrap the value in an array [x].
429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Create or update multiple email-only users​

Creates or updates up to 20 email-only users. An email-only user is a recipient of a delivery that isn't associated with an Omni account.

If Omni matches a provided email to an existing email-only user, the user will be updated according to the userAttributes in the request body.

POST /api/v1/users/email-only/bulk
curl -X POST'https://myorg.omniapp.co/api/v1/users/email-only/bulk' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer <TOKEN>' \
--data '{
   "users":[
      {
         "email":"iamagoodblob@myorg.co"
      },
      {
         "email":"blobmanager@myorg.co"
      }
   ]
}'

Parameters​

Loading parameters...

Response​

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

200 OK
{
    "results": [
        {
            "email": "iamagoodblob@myorg.co",
            "userId": "1e23dadc-961b-4a21-b36b-17168130fc3f"
        },
        {
            "email": "blobmanager@myorg.co",
            "userId": "e9d19f71-0b59-4f8e-8343-a75d30576d28"
        }
    ]
}
400 Bad Request
{
  "detail": "<errorReason>",
  "status": 400
}
ErrorError detail
Invalid JSON in request bodyInvalid JSON
Maximum users exceededusers: Maximum of 20 users can be processed in a single request
Missing users parameterusers: users is required
Missing email parameteremail: email is required
email value isn't a valid email addressemail: Invalid email address
User attribute does not existThe provided user attributes: \"<attribute>\" do not match the names of existing user attributes.
User attribute type mismatchUser Attribute <attribute> is type number, but passed-in value <value> is not a number.
Invalid omni_user_timezone valueThe timezone <invalidTimezone> is not supported. Please see the connection page or user profile page for the list of valid timezones. Use e.g. \"America/New_York\" instead of \"EST\"
Multiple values not provided as arrayUser Attribute <attribute> has multiple values enabled, but the passed-in value is not an array. If passing a single value for a user attribute with multiple values enabled, please wrap the value in an array [x].
429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.