Email Send API � Entity Validation and Error Codes

The TrustPager email send endpoint (POST /v1/email/send) validates any entity IDs in your payload before dispatching. If an ID references a contact, opportunity, or company that no longer exists in the workspace, the request is rejected with a 400 � the email is not sent. This prevents ghost threads appearing in the Inbox with "No messages in this thread".

Error codes

400 VALIDATION_ERROR � invalid entity ID

Returned when one or more of contact_id, deal_id / opportunity_id, or customer_id / company_id cannot be found in the workspace. The email is not sent.

Response body shape:

{
  "error": "VALIDATION_ERROR",
  "details": {
    "missing_entities": [
      { "field": "contact_id", "id": "<uuid>" }
    ]
  }
}

details.missing_entities lists every bad field in the payload � you may get more than one entry if multiple IDs are stale.

422 EMAIL_LOG_FAILED � email delivered, log not persisted

Returned when TrustPager Mail accepted the send and the email was delivered to the recipient, but the internal log row could not be written. The email reached the recipient. The response body includes the provider message ID so you have a delivery reference:

{
  "error": "EMAIL_LOG_FAILED",
  "message_id": "<provider-message-id>"
}

This is distinct from EMAIL_DELIVERY_FAILED, which means the email was not delivered. If you receive EMAIL_LOG_FAILED, the send succeeded � the log entry just won't appear in https://app.trustpager.com/data/emails.

Three valid payload shapes

Shape	What to pass	Result
Linked send	A current, valid entity UUID in contact_id, opportunity_id, or company_id	Email sends, log created, thread links to the entity in Inbox and the entity's activity feed
Unlinked send	Omit the entity fields entirely, or pass null	Email sends, log created, thread appears in Inbox unlinked. This is the standard path for free-form sends to an arbitrary address
Stale ID	A UUID that no longer exists in the workspace	400 VALIDATION_ERROR � email not sent. Fix the ID or omit the field

Troubleshooting

• Getting 400 VALIDATION_ERROR on an ID you believe is current � confirm the entity still exists by fetching it directly (GET /v1/contacts/:id, GET /v1/opportunities/:id, or GET /v1/companies/:id). The entity may have been deleted by an automation, a workspace cleanup, or another user since the ID was stored.
• Email arrived but isn't showing in Inbox � check https://app.trustpager.com/data/emails. If the row is missing, the send may have returned EMAIL_LOG_FAILED � use the message_id from the response body for your own records. If the row is present but the thread shows "No messages", the entity link was stale at the time of an older send (before this validation was added).
• MCP callers � the send_email MCP tool passes these fields through to the same endpoint. The same error codes apply; the tool surfaces VALIDATION_ERROR details in its response.