Create a new email message record. Optionally send the email by setting send: true.

Default behavior (send: false or omitted):

• Creates a record in the CRM without sending
• Use this to log emails sent through external systems

Sending emails (send: true):

• Uses team's default provider if emailProviderId is not specified
• Optionally specify emailProviderId to use a specific provider
• Actually sends the email through the specified/default provider
• Provider must be configured and accessible to the API token

Custom email headers:

• Supply an optional headers object alongside subject and body, either at the root or inside emailMessage.
• Header names and string values pass through verbatim to the sending provider. Every provider the Partner API can send through emits them — SendGrid, Mailgun, Mandrill, SMTP, and Gmail — including List-Unsubscribe and List-Unsubscribe-Post.
• For one-click unsubscribe, set List-Unsubscribe to <https://your-domain.com/unsubscribe/recipient-token> and List-Unsubscribe-Post to List-Unsubscribe=One-Click. Your HTTPS endpoint must process the unsubscribe POST.
• Header names must be nonempty printable ASCII without spaces or colons, and unique ignoring case. Values must be strings without CR, LF, or null bytes.
• At most 50 headers per message. Names are limited to 200 characters, and each full header line (Name: value) to 998 bytes — the RFC 5322 line limit. A long value with no spaces cannot be folded, so keep unsubscribe URLs under that budget.
• A value that is not pure ASCII is measured as the RFC 2047 encoded word the provider puts on the wire, where each non-ASCII byte costs three octets plus a 12-octet wrapper — roughly 163 accented characters fit a short header name.
• Reserved headers are rejected: X-SG-ID, X-SG-EID, Received, DKIM-Signature, Content-Type, Content-Transfer-Encoding, Content-Disposition, Content-ID, Content-Description, To, From, Subject, Reply-To, Cc, Bcc, Sender, Return-Path, MIME-Version, X-SMTPAPI, Message-ID, Date, In-Reply-To, References, and any Resent- header. Use fromEmail and toEmail for sender and recipient addresses; the provider stamps the message id, date, and threading headers.
• Invalid headers return HTTP 422 before recording or sending the email. Omit headers or use {} when none are needed. With send: false, headers are recorded without sending.
• The recorded headers are echoed back as headers in this response and in GET /emailMessages(/{id}), so you can verify what was stored and sent. Only messages created through this endpoint carry a headers field; messages synced in from a connected Gmail or Outlook mailbox omit it.
• Rejected requests count toward the per-token circuit breaker like any other non-2xx response (20 consecutive failures pause the token for 5 minutes), so validate header values client-side rather than by retrying.

Auto-fill behavior:

• If toEmail is blank/omitted, uses the person's primary email (or returns error if none exists)
• If fromEmail is blank/omitted, uses the default email provider's sender email (or returns error if no provider configured)
• This allows simplified message creation when using default contact information