Verified · 8/11/2026

Primitive Contract Types Reference

Reference for the producer-side TypeScript types exported from @primitivedotdev/sdk/contract, used to build schema-valid email.received webhook payloads and test fixtures byte-for-byte.

What the contract module is for#

@primitivedotdev/sdk/contract is a Node-only subpath of @primitivedotdev/sdk that exports the producer-side types and builder functions for the email.received webhook payload. Where the rest of the SDK (@primitivedotdev/sdk/webhook) is built for consuming an EmailReceivedEvent you received, contract is built for constructing one: writing test fixtures, building a mock webhook sender, or emitting payloads from a Primitive Function that fans events out to another system.

For the builder calls themselves (buildEmailReceivedEvent, buildEventFromParsedData), see Building Webhook Payloads (Contract Module). For the consumer-side normalized object, see Receiving Inbound Email.

Note

contract is one of the SDK's two Node-only subpaths (the other is parser). Use it in test fixtures, scripts, and server-side tooling.

Input types#

These are the "what you supply" shapes. The builder functions in @primitivedotdev/sdk/contract take one of these and return an event that validates against the canonical webhook schema at json-schema/email-received-event.schema.json.

Type	Purpose
`EmailReceivedEventInput`	Top-level input to `buildEmailReceivedEvent`.
`ParsedInput`	The `email.parsed` sub-object input, consumed by `buildEventFromParsedData`.
`RawContentInline`	The `email.content.raw` variant where the raw MIME bytes are carried inline.
`RawContentDownloadOnly`	The `email.content.raw` variant where the raw bytes are not inline and must be downloaded instead.

Note

This page indexes the types. For the builder call and the field values a typical fixture supplies, see Building Webhook Payloads (Contract Module).

`RawContentInline` vs. `RawContentDownloadOnly`#

Both describe email.content.raw, and a fixture picks exactly one of the two variants; mixing them produces a payload that fails schema validation the same way a malformed real payload would. The split mirrors the real API's behavior: a small message ships its raw MIME inline, and a larger one ships a download URL instead. Fixtures that exercise your download-path code should use RawContentDownloadOnly; everything else should use RawContentInline.

Builder functions#

The two builder functions consume the input types above and return a fully schema-valid event. Full parameter-by-parameter documentation, including which fields are required vs. defaulted, lives on Building Webhook Payloads (Contract Module).

Function	Input type	Output
`buildEmailReceivedEvent`	`EmailReceivedEventInput`	A complete `EmailReceivedEvent`
`buildEventFromParsedData`	`ParsedInput`	A complete `EmailReceivedEvent`, built starting from parsed-body data rather than full event fields

These are not exported from contract; they're the types you get back when receiving mail, documented on their owning pages. Listed here only so you don't confuse a producer-side input type with its consumer-side counterpart of a similar name.

Type	Where it's documented	Relationship to this page
`EmailReceivedEvent`	Receiving Inbound Email	The output of both builder functions above, and the type validated by `validateEmailReceivedEvent`
`ReceivedEmail`	Receiving Inbound Email	The normalized shape `primitive.receive(...)` returns; built from an `EmailReceivedEvent`, not from a contract input type
`WebhookAttachment`	Parsing Raw Email (.eml)	The attachment shape carried on `EmailReceivedEvent.email.parsed.attachments`