Imports an existing email into Daylite and links it to records. This doesn't send email, and it doesn't fetch messages from a mail server: you supply the email's details yourself.

Importing an email takes two requests:

1. Create the email record with this endpoint. It returns the new email's location.
2. Upload the body with Email Body, using PUT on that location plus /body.

Both requests need a token with the daylite:write scope.

Creating the email record

message_id and from are required:

{
  "message_id": "<[email protected]>",
  "from": "Jane Smith <[email protected]>",
  "to": "[email protected], Sam Lee <[email protected]>",
  "subject": "Re: Proposal",
  "date": "2025-03-04T17:40:00Z",
  "contacts": [{ "contact": "/v1/contacts/1000" }]
}

🚧

message_id must be unique

message_id is the email's Message-ID header, and each email needs its own value, e.g. <[email protected]>. The Daylite app and Daylite Mail Assistant rely on it to identify emails, and replies refer to it through parent_message_id. The API does not reject duplicates, so make sure you never reuse a value. When importing a real email, use its original Message-ID.

to, cc and bcc are sent as one comma-separated string. date can only be set here, not later.

The body isn't part of this request. Upload it afterwards with Email Body.

A successful request returns 201 Created with the new email's reference, e.g. {"location": "/v1/emails/4005"}.

Links use the same format as other records, e.g. "contacts": [{ "contact": "/v1/contacts/456" }]. The supported links are appointments, contacts, companies, forms, groups, notes, opportunities, projects and tasks. Recipient addresses are not matched to contacts or companies automatically, so add the links you want yourself. The user making the request is recorded as the email's creator, and is its owner unless you set owner.

Retries and duplicates

• Creating the record and uploading the body are separate requests. If the body upload fails, the email record still exists. Retry the upload against the same location; don't create the email again.
• Creating an email is not idempotent, and the API doesn't detect duplicates by message_id. Keep a mapping from your source email's ID to the returned location so a retry or re-import doesn't create a second copy.
• date is when the email was sent. It is separate from create_date, which is when the record was added to Daylite.
• Fields that can be set when creating an email can't necessarily be changed later: subject, from, to, cc and bcc are normally protected after creation, and the body can only be set once.

Errors

• 400 with {"error":"invalid_json"} if the request body isn't a JSON object.
• 400 with a JSON object keyed by attribute if validation fails, e.g. {"message_id": [{"error": "blank"}]}.
• 403 with {"error":"not_authorized_for_object_creation"} if the token lacks the daylite:write scope.