Email — Send & Manage

Send new emails, reply to and forward existing messages, delete emails, and modify properties like read status and labels.

POST/api/access/email/messages/sendBearer Token

Send Email

Sends a new email from one of the connected provider accounts.

Request Body

Field	Type	Required	Description
to	Participant[]	Yes	List of recipients
cc	Participant[]	No	CC recipients
bcc	Participant[]	No	BCC recipients
subject	string	Yes	Email subject
body	string	Yes	Email body content
bodyType	string	No	Body content type: html (default) or text
importance	string	No	Priority: low, normal (default), high
sendFrom	string	No	Email address of the account to send from (e.g. "user@gmail.com"). Only needed when multiple email providers are connected. If omitted, the default connection is used
connectionId	long	No	Provider connection to send from. If omitted, uses the first active email-capable connection

{ 
  "to": [ 
    { "email": "recipient@example.com", "name": "John Doe" } 
  ], 
  "cc": [ 
    { "email": "cc@example.com", "name": "CC Person" } 
  ], 
  "subject": "Meeting Follow-up", 
  "body": "<p>Thanks for meeting today. Here are the action items...</p>", 
  "bodyType": "html", 
  "importance": "normal", 
  "sendFrom": "work@gmail.com" 
}

Response Fields

Field	Type	Description
success	bool	Whether the send operation succeeded
emailId	string?	Provider-prefixed ID of the sent email
threadId	string?	Provider-prefixed thread ID (Gmail only; M365 returns null)
errorMessage	string?	Error details when success is false

Note

Gmail returns the sent message's emailId and threadId. Microsoft 365 returns null for both (Graph API's sendMail endpoint returns 202 Accepted with no message ID). Use sendFrom to specify which email address sends the message when multiple providers are connected, or connectionId to target a specific provider connection by ID.

Error Responses

Status	Description
403	Token does not allow sending emails
422	Email access is not enabled for this token (EMAIL_NOT_ENABLED)
422	No email provider is connected (NO_EMAIL_PROVIDER)

POST/api/access/email/messages/{emailId}/replyBearer Token

Reply to Email

Replies to an existing email. Automatically threads the reply with the original message.

Path Parameters

Parameter	Type	Description
emailId	string	Provider-prefixed email ID to reply to

Request Body

Field	Type	Required	Description
body	string	Yes	Reply body content
bodyType	string	No	Body content type: html (default) or text
replyAll	bool	No	Reply to all recipients (default: false)

{ 
  "body": "<p>Thanks, I'll review this and get back to you.</p>", 
  "bodyType": "html", 
  "replyAll": false 
}

Response Fields

Field	Type	Description
success	bool	Whether the send operation succeeded
emailId	string?	Provider-prefixed ID of the sent email
threadId	string?	Provider-prefixed thread ID (Gmail only; M365 returns null)
errorMessage	string?	Error details when success is false

Note

Gmail automatically threads the reply using In-Reply-To and References headers. The Re: prefix is added if not present. When replyAll is true, the original To/Cc recipients are included (excluding the sending account). Microsoft 365 uses the native /reply or /replyAll Graph API endpoint.

Error Responses

Status	Description
403	Token does not allow replying to emails
422	Email access is not enabled for this token (EMAIL_NOT_ENABLED)
422	No email provider is connected (NO_EMAIL_PROVIDER)

POST/api/access/email/messages/{emailId}/forwardBearer Token

Forward Email

Forwards an email to specified recipients.

Path Parameters

Parameter	Type	Description
emailId	string	Provider-prefixed email ID to forward

Request Body

Field	Type	Required	Description
to	Participant[]	Yes	Forward recipients
cc	Participant[]	No	CC recipients
body	string	No	Optional message to prepend
bodyType	string	No	Body content type: html (default) or text

{ 
  "to": [ 
    { "email": "colleague@example.com", "name": "Colleague" } 
  ], 
  "body": "FYI — see the email below." 
}

Response Fields

Field	Type	Description
success	bool	Whether the send operation succeeded
emailId	string?	Provider-prefixed ID of the sent email
threadId	string?	Provider-prefixed thread ID (Gmail only; M365 returns null)
errorMessage	string?	Error details when success is false

Error Responses

Status	Description
403	Token does not allow forwarding emails
422	Email access is not enabled for this token (EMAIL_NOT_ENABLED)
422	No email provider is connected (NO_EMAIL_PROVIDER)

DELETE/api/access/email/messages/{emailId}Bearer Token

Delete Email

Soft-deletes an email. The email is moved to Trash/Deleted Items and can be recovered.

Path Parameters

Parameter	Type	Description
emailId	string	Provider-prefixed email ID to delete

Response 204 No Content

(empty response body)

Note

Gmail moves the email to Trash (recoverable for 30 days). Microsoft 365 moves it to the Deleted Items folder. This is a soft delete — emails are not permanently destroyed.

Error Responses

Status	Description
404	Email not found or could not be deleted
422	Email access is not enabled for this token (EMAIL_NOT_ENABLED)
422	No email provider is connected (NO_EMAIL_PROVIDER)

PATCH/api/access/email/messages/{emailId}Bearer Token

Modify Email

Modifies email properties such as read status and labels/categories.

Path Parameters

Parameter	Type	Description
emailId	string	Provider-prefixed email ID to modify

Request Body

Field	Type	Required	Permission	Description
markAsRead	bool	No	mark_as_read	Mark as read (true) or unread (false)
addLabels	string[]	No	apply_labels	Labels/categories to add
removeLabels	string[]	No	apply_labels	Labels/categories to remove

{ 
  "markAsRead": true, 
  "addLabels": ["IMPORTANT"], 
  "removeLabels": ["UNREAD"] 
}

Note

Each sub-operation requires its own permission flag. A token with mark_as_read but not apply_labels can mark emails as read but cannot modify labels. Gmail uses messages/modify with label IDs. Microsoft 365 patches isRead and categories.

Error Responses

Status	Description
404	Email not found or could not be modified
422	Email access is not enabled for this token (EMAIL_NOT_ENABLED)
422	No email provider is connected (NO_EMAIL_PROVIDER)