Email Notifications

Learn how to create and verify email notification channels to receive automated emails for Unstructured workflow job events.

Email notification channels are endpoints that send automated emails when workflow job events occur. Similar to webhooks, they allow you to automate notifications to specified recipients.

Email notification channels are only available through the Unstructured API.

You can create email notification channels at the workspace or workflow level:

• Workspace-scoped notification channels send emails when the selected events occur on jobs for all workflows in the workspace.
• Workflow-scoped notification channels send emails when the selected events occur on jobs for just the specified workflow.

Email notification channels support the following event types:

Event type	Description
job.scheduled	Job queued to run
job.in_progress	Job has started
job.completed	Job finished processing
job.stopped	Job has stopped
job.failed	Job failed to initialize without processing any files

Create the email channel

To create an email notification channel, use the Unstructured API:

• For workspace-scoped channels, use Create notification channel.
• For workflow-scoped channels, use Create workflow notification channel.

In each case, the response will include the unique identifier for the notification channel, which you will use to verify the channel.

{
    "channel_type": "email",
    "id": "ep_0a1B2c3D4e5F6g7H8i9J0k1L2m3N",
    . . . 
    "enabled": false,
    . . . 
}

Once the notification channel is created, Unstructured will send a verification code to the recipient email address. You will need this code to verify the channel.

The following example creates an email notification channel that sends notifications for all job status events to the specified email address:

cURL

curl --request POST \
 --url "${UNSTRUCTURED_API_URL}/api/v1/notifications/channels" \
 --header "Content-Type: application/json" \
 --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
 --data '{
    "channel_type": "email",
    "description": "Workspace level job events",
    "event_types": ["job.completed", "job.scheduled", "job.in_progress", "job.stopped", "job.failed"],
    "email_config": {
      "recipient_email": "[e-mail]"
    }
  }'

The following example creates an email notification channel that sends notifications only for the specified workflow, and just for jobs that have failed:

cURL

curl --request POST \
  --url "${UNSTRUCTURED_API_URL}/api/v1/workflows/12345678-1234-1234-1234-123456789012/notifications/channels" \
  --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "channel_type": "email",
    "event_types": ["job.failed"],
    "description": "Workflow-specific status alerts",
    "email_config": {
      "recipient_email": "[e-mail]"
    }
  }'

Verify the email channel

Unstructured creates email notification channels in a disabled state, and they require verification before they can receive notifications. To verify a channel, use the Unstructured API:

• For workspace-scoped channels, use Verify notification channel.
• For workflow-scoped channels, use Verify workflow notification channel.

To use these APIs, you need two pieces of information:

• The channel ID, which is included in the response when you create the channel.
• The verification code, which is a six-digit code sent to the recipient email address when you create the channel.

A response with an HTTP status code of 204 No Content indicates that the channel is now verified and active.

The following example verifies a workspace-scoped email notification channel:

cURL

curl --request POST \
  --url "${UNSTRUCTURED_API_URL}/api/v1/notifications/channels/ep_9Z8y7X6w5V4u3T2s1R0q9P8o7N6m/verify" \
  --header "Content-Type: application/json" \
  --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
  --data '{
    "code": "123456"
  }'

The following example verifies a workflow-scoped email notification channel:

cURL

curl --request POST \
  --url "${UNSTRUCTURED_API_URL}/api/v1/workflows/12345678-1234-1234-1234-123456789012/notifications/channels/ep_1a2B3c4D5e6F7g8H9i0J1k2L3m4N/verify" \
  --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "code": "123456"
  }'

Test the email channel

To test an email notification channel, run a workflow job and check your email inbox for the specified notifications.