Forward Message

Warning

Paid tier required - Sending emails requires a paid tier subscription.

Authentication

Requires the inbox's API key in the Authorization header.

Path Parameters

idstringpathrequired

Inbox ID (e.g., inb_abc123)

msgIdstringpathrequired

Message ID of the email you're forwarding (e.g., msg_xyz789)

Request Body

tostring or arraybodyrequired

Recipient email address(es) for the forwarded message

ccstring or arraybody

CC recipients (optional)

bccstring or arraybody

BCC recipients (optional)

subjectstringbody

Subject line (defaults to "Fwd: [original subject]")

bodystringbodyrequired

Introduction text to prepend before the forwarded content

body_htmlstringbody

HTML introduction text (optional)

include_attachmentsbooleanbody

Whether to include attachments from the original message

client_idstringbody

Idempotency key - prevents duplicate sends on retry

send_atstringbody

ISO 8601 datetime - schedule for future delivery (optional)

Request

curl -X POST "https://api.daimon.email/v1/inboxes/inb_abc123/messages/msg_xyz789/forward" \
  -H "Authorization: Bearer dm_live_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "colleague@example.com",
    "body": "FYI - see below for context.",
    "include_attachments": true,
    "client_id": "forward-001"
  }'

const client = new DaimonClient({ apiKey: 'dm_live_...' });

const forwarded = await client.inboxes.messages.forward('inb_abc123', 'msg_xyz789', {
  to: 'colleague@example.com',
  body: 'FYI - see below for context.',
  includeAttachments: true,
  clientId: 'forward-001'
});

console.log(`Forwarded to: ${forwarded.recipients.to.join(', ')}`);
console.log(`Status: ${forwarded.status}`);

client = DaimonClient(api_key='dm_live_...')

forwarded = client.inboxes.messages.forward('inb_abc123', 'msg_xyz789', {
    'to': 'colleague@example.com',
    'body': 'FYI - see below for context.',
    'include_attachments': True,
    'client_id': 'forward-001'
})

print(f"Forwarded to: {', '.join(forwarded.recipients['to'])}")
print(f"Status: {forwarded.status}")

Response

{
  "result": {
    "id": "msg_fwd123",
    "status": "sent",
    "message_id": "<fwd123@daimon.email>",
    "sent_at": "2024-03-11T14:30:15Z",
    "recipients": {
      "to": ["colleague@example.com"],
      "cc": [],
      "bcc": []
    }
  },
  "next_steps": [
    "Message forwarded successfully",
    "Original message content and attachments included",
    "Check /v1/inboxes/{id}/messages for replies"
  ]
}

{
  "error": "SEND_REQUIRES_PAID",
  "message": "Sending emails requires a paid tier subscription",
  "upgrade_context": {
    "operator_action_url": "https://daimon.email/upgrade?token=...",
    "operator_action_label": "Add a payment method to enable sending",
    "agent_script": "Tell your operator: I need sending access. Here's a direct upgrade link: https://daimon.email/upgrade?token=..."
  },
  "next_steps": [
    "Present the upgrade link to your operator",
    "After upgrade, retry with the same client_id for idempotency"
  ]
}

Response Fields

result.idstring

Forwarded message ID

result.statusstring

Delivery status: queued, sent, or scheduled

result.message_idstring

RFC 5322 Message-ID header of the forwarded message

result.sent_atstring

ISO 8601 timestamp of when the message was sent

result.recipientsobject

Object containing to, cc, and bcc arrays

next_stepsarray

Agent guidance for next actions

Forwarding Behavior

When you forward a message, daimon.email:

Prepends your introduction text before the original message content
Adds "Fwd: " to the subject if not already present
Includes original headers in the forwarded content (From, To, Date, Subject)
Copies attachments (if include_attachments: true)
Does NOT set In-Reply-To - forwarding creates a new conversation, not a reply

Example Format

[Your introduction text]

---------- Forwarded message ---------
From: Original Sender <sender@example.com>
Date: Mon, 11 Mar 2024 10:15:30 +0000
Subject: Original Subject
To: my-agent@daimon.email

[Original message content]

Use Cases

Forward verification emails to operator

// Agent receives a verification email and forwards to human
const messages = await client.inboxes.messages.list('inb_abc123', {
  label: 'verification',
  limit: 1
});

if (messages.messages.length > 0) {
  const msg = messages.messages[0];

  await client.inboxes.messages.forward('inb_abc123', msg.id, {
    to: 'operator@mycompany.com',
    body: 'I received a verification email. Please click the link to verify.',
    clientId: `fwd-verify-${msg.id}`
  });
}

Forward to multiple recipients

await client.inboxes.messages.forward('inb_abc123', 'msg_xyz789', {
  to: ['alice@example.com', 'bob@example.com'],
  cc: ['manager@example.com'],
  body: 'Team - please review this request.',
  clientId: 'team-fwd-001'
});

Forward without attachments

// Forward only the message text, not attachments
await client.inboxes.messages.forward('inb_abc123', 'msg_xyz789', {
  to: 'colleague@example.com',
  body: 'See message below (attachments omitted for size).',
  includeAttachments: false,
  clientId: 'fwd-no-attach-001'
});

Scheduled forward

// Schedule a forward for tomorrow morning
await client.inboxes.messages.forward('inb_abc123', 'msg_xyz789', {
  to: 'colleague@example.com',
  body: 'FYI for Monday morning review.',
  sendAt: '2024-03-12T09:00:00Z',
  clientId: 'scheduled-fwd-001'
});

On this page