This feature has not been released publicly, and we politely request that you treat everything in this document as confidential.

All details outlined in this document are in beta. We may change the timeline, APIs, and functionality based on feedback from pilot testers like yourself, so you should be prepared to update your code accordingly.

Email Upload API Beta

This is the early access API documentation for uploading emails to a Slack channel via Slack APIs. Using this API, developers can upload raw email (a.k.a .eml file, original email) or JSON representation of the email to Slack.

Most of Slack's APIs are synchronous in nature. However the Email Upload API works asynchronously, due to the time variance in email processing.

Understanding Emails in Slack

The Email Upload API is a new way to represent an external work object in Slack (see Remote Files). When working in Slack it's inconvenient to leave to check an email client. It is also very hard to collaborate effectively through email. This new API allows emails to be brought into Slack and also creates a new object type specific to email.

There are many use cases when the Email Upload API can be useful. For example, allowing users to triage emails directly in Slack can streamline workflows and allow users to maintain focus.

Triage

For emails that are time sensitive and cannot wait for the user to eventually see a message, it can be useful to send the email directly to Slack where it will be noticed quickly.

TimeSensitive

Relevant scopes

These APIs use the new emails:write scope. This scope is not available to the developers yet. Please reach out to us with the App ID of your Slack app so that we can enable this for your app.

Scope	Description
bot	Gives the bot permissions to upload emails into Slack
emails:write	Allows a user token to upload emails into Slack

API Beta Reference

email.upload

Send an email to Slack

Required scope: bot or emails:write

Preferred HTTP method: POST

Argument Details

Name	Example	Required	Description
token	xxxx-xxxxxxxxx-xxxx	Required	Authentication token bearing required scopes.
channel_id	C1234567890	Optional	Channel ID where the email will be shared.
comment	Checkout this email!	Optional	The text introducing the email in specified channel.
email	...	Optional	File contents via multipart/form-data. If present, other email parameters will be omitted.
email_json	...	Optional	A JSON object representing email data. See the examples below
thread_ts	1234567890.123456	Optional	Provide another message's `ts` value to make this email a reply.

Sample Request:

POST /api/email.upload HTTP/1.1
Host: slack.com
Content-Type: application/json;charset=utf-8
Authorization: Bearer xoxp-{token}
{
	"channel_id": "CDRKNCMG9",
	"as_user": false,
	"comment": "*Hey, John. Thanks for your help today.* Click to see full email :point_down:  ",
	"email_json": {
		"message_id": "67593751008",
		"from": "Jane Stevenson <sender@example.com>",
		"to": ["John Doe <user2@example.com>"],
		"cc": ["cc-user1@example.com"],
		"date_sent": "1547747889",
		"subject": "Reports on important things",
		"body_plain": "Hello!\n Please see the attached file.",
		"body_html": "<html><head></head><body>Hey John, <p>Thanks for your help today.</p></body></html>"
	}
}

Sample Response:

{
    "ok": true,
    "ticket_id": 12345567
}

Note: The ticket_id is used to query if the email has been uploaded

email.uploadStatus

Used to determine the upload status of an email. This API will return status of up to 10 tickets in single API call.

Required scope: bot or emails:write

Preferred HTTP method: POST

Argument Details

Name	Example	Required	Description
token	xxxx-xxxxxxxxx-xxxx	Required	Authentication token bearing required scopes.
ticket_ids	[123456,876543]	Required	A JSON-based array of ticket ids. Maximum of 10 tickets per request.
exclude_email_object	false	Optional	If `false`, the response will contain the shared email file. Default is `true` Sending exclude_email_object: false will return the shared email object. Please use this only if necessary.

Sample Request:

POST /api/email.uploadStatus HTTP/1.1
Host: slack.com
Authorization: Bearer xoxp-{token}
Content-Type: application/json;charset=utf-8
{
	"ticket_ids": ["574911449393"]
}

Sample Response

{
    "ok": true,
    "tickets": [
        {
            "ticket_id": 574911449393,
            "status": "complete"
        }
    ]
}

Errors

Error	Description
`failed_to_parse_file`	Error reading email, something wrong in the file uploaded.
`failed_to_download_file`	This is an internal error please report an issue if you see this error.
`email_max_filesize`	If email is more than 25MB.
`too_many_attachments`	More than 20 attachments per email.
`max_snippet_size` or `max_payload`	When email payload (i.e email body + headers + attachment metadata ) is greater than allowed size (currently this is 1MB).
`json_encode_failed`	Error in email data.
`attachment_upload_failed`	Failed to upload one of the email attachments.