Skip to main content
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 typeDescription
job.scheduledJob queued to run
job.in_progressJob has started
job.completedJob finished processing
job.stoppedJob has stopped
job.failedJob failed to initialize without processing any files
The following 3-minute video provides an overview of email notification channels:
The following 5-minute video shows how to use the Unstructured API to create and verify email notification channels:

​
Create the email channel

To create an email notification channel, use the Unstructured API: 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": "donotreply@example.com"
    }
  }'
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": "donotreply@example.com"
    }
  }'

​
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: 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.