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.
Endpoint
Section titled “Endpoint”/messages/send Request body
Section titled “Request body”Content-Type required
All POST requests must include Content-Type: application/json header.
channelId string Required microsoft365 channelto string Required [email protected])subject string Required body string Required bodyType string Optional html or text. Defaults to htmlcc array Optional bcc array Optional contact object Optional Show 2 child fields Hide 2 child fields
name string Optional tags array Optional Example request
Section titled “Example request”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", "to": "[email protected]", "subject": "Your order is confirmed", "body": "<p>Hi John,</p><p>Your order <strong>#12345</strong> has been confirmed.</p>", "bodyType": "html" }'Example with CC, BCC, and contact
Section titled “Example with CC, BCC, and contact”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", "to": "[email protected]", "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"] } }'Success response
Section titled “Success response”{ "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" }}Contact auto-creation
Section titled “Contact auto-creation”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 }}Errors
Section titled “Errors”VAL_004 400 A required field (channelId, to, subject, or body) is missing from the request body.
VAL_006 400 The recipient email address is not a valid format.
RES_001 404 The specified channel was not found or you don't have access to it.
BIZ_001 422 The Microsoft 365 channel is not currently connected. Reconnect it from the Channels settings page.
SRV_002 500 Failed to send the email via Microsoft Graph API. The access token may need to be refreshed — try reconnecting the channel.
Error response example
Section titled “Error response example”{ "success": false, "error": { "code": "BIZ_001", "message": "The channel is not currently connected" }}