Home/Mail/Data Structures

Mail Data Structures

Field definitions for key objects returned by Mail APIs.

ID Format

Resources use prefixed public IDs (for example deal_..., inv_..., form_..., ak_...).

Message object

Object representing a sent email message.

Fields

Name	Type	Required	Description
id	string	Required	Message ID
object	string	Required	Object type (`mail.message`)
organization_id	string	Required	Organization ID
to	string	Required	Recipient email
subject	string	Required	Subject
status	"queued" \| "sent" \| "delivered" \| "bounced" \| "failed"	Required	Delivery status
sent_at	string \| null	Optional	Sent at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)

{
  "id": "msg_01JQ3KXYZ",
  "object": "mail.message",
  "organization_id": "org_01HZXYZ",
  "to": "user@example.com",
  "subject": "Your invoice is ready",
  "status": "delivered",
  "sent_at": "2026-02-20T10:00:00Z",
  "created_at": "2026-02-20T09:55:00Z"
}

Contact object

Object representing a mail delivery contact.

Fields

Name	Type	Required	Description
id	string	Required	Contact ID
object	string	Required	Object type (`mail.contact`)
organization_id	string	Required	Organization ID
email	string	Required	Email address
name	string \| null	Optional	Name
is_unsubscribed	boolean	Required	Unsubscribed flag
created_at	string	Required	Created at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "mc_01JQ3KDEF",
  "object": "mail.contact",
  "organization_id": "org_01HZXYZ",
  "email": "tanaka@example.com",
  "name": "Tanaka Taro",
  "is_unsubscribed": false,
  "created_at": "2026-01-15T09:00:00Z",
  "updated_at": "2026-02-18T11:00:00Z"
}

Campaign object

Object representing an email campaign.

Fields

Name	Type	Required	Description
id	string	Required	Campaign ID
object	string	Required	Object type (`mail.campaign`)
organization_id	string	Required	Organization ID
name	string	Required	Campaign name
subject	string	Required	Subject
status	"draft" \| "scheduled" \| "sending" \| "sent" \| "cancelled"	Required	Status (draft, scheduled, sending, sent, cancelled)
list_id	string	Required	Mailing list ID
sent_at	string \| null	Optional	Sent at
created_at	string	Required	Created at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "camp_01JQ3KGHI",
  "object": "mail.campaign",
  "organization_id": "org_01HZXYZ",
  "name": "February Newsletter",
  "subject": "What's new in February",
  "status": "sent",
  "list_id": "list_01JQ3KJKL",
  "sent_at": "2026-02-15T09:00:00Z",
  "created_at": "2026-02-10T14:00:00Z",
  "updated_at": "2026-02-15T09:00:00Z"
}