Skip to content
DutiesBook API
Open app

Send email

Send an email to any recipient using a connected Microsoft 365 Outlook channel. Supports HTML and plain-text bodies, CC/BCC recipients, and automatic contact creation.

POST /messages/send

Content-Type required

All POST requests must include Content-Type: application/json header.

channelId string Required
UUID of a connected microsoft365 channel
to string Required
Recipient email address (e.g., [email protected])
subject string Required
Email subject line
body string Required
Email body content — HTML or plain text
bodyType string Optional
Content type of the body: html or text. Defaults to html
cc array Optional
CC recipient email addresses
bcc array Optional
BCC recipient email addresses
contact object Optional
Contact information for auto-creation
Show 2 child fields Hide 2 child fields
name string Optional
Display name for the contact record in DutiesBook
tags array Optional
Tags to assign to the contact
Content-Type: application/json
X-Account-Id: acc_12345678
X-Api-Key: pk_abcdefghij
X-Secret-Key: sk_1234567890abcdef
Terminal window
curl -X POST https://app.dutiesbook.com/api/external/v1/messages/send \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"subject": "Your order is confirmed",
"body": "<p>Hi John,</p><p>Your order <strong>#12345</strong> has been confirmed.</p>",
"bodyType": "html"
}'
Terminal window
curl -X POST https://app.dutiesbook.com/api/external/v1/messages/send \
-H "Content-Type: application/json" \
-H "X-Account-Id: acc_xxxxxxxx" \
-H "X-Api-Key: pk_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-d '{
"channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"subject": "Your order is confirmed",
"body": "<p>Hi John,</p><p>Your order <strong>#12345</strong> has been confirmed.</p>",
"bodyType": "html",
"cc": ["[email protected]"],
"bcc": ["[email protected]"],
"contact": {
"name": "John Smith",
"tags": ["customer", "vip"]
}
}'
200 OK
{
"success": true,
"data": {
"messageId": "AAMkAGI2TG93AAA=",
"status": "sent",
"subject": "Your order is confirmed",
"contact": {
"uuid": "contact-uuid",
"displayName": "John Smith",
"isNew": false
},
"sentAt": "2024-01-15T10:30:00Z"
}
}

Automatic contact creation

When sending to an email address that does not exist in your contacts, a new contact is automatically created in your organization.

If contact.name is provided it is used as the display name in DutiesBook. If omitted, the recipient email address is used instead. Tags in contact.tags are assigned immediately on creation.

Example response when a new contact is created:

{
"contact": {
"uuid": "new-contact-uuid",
"displayName": "John Smith",
"isNew": true
}
}
VAL_004 400
MISSING_REQUIRED_FIELD

A required field (channelId, to, subject, or body) is missing from the request body.

VAL_006 400
INVALID_EMAIL_ADDRESS

The recipient email address is not a valid format.

RES_001 404
CHANNEL_NOT_FOUND

The specified channel was not found or you don't have access to it.

BIZ_001 422
CHANNEL_NOT_CONNECTED

The Microsoft 365 channel is not currently connected. Reconnect it from the Channels settings page.

SRV_002 500
MICROSOFT_API_ERROR

Failed to send the email via Microsoft Graph API. The access token may need to be refreshed — try reconnecting the channel.

422 Unprocessable Entity
{
"success": false,
"error": {
"code": "BIZ_001",
"message": "The channel is not currently connected"
}
}