Methods changes

For each endpoint in the v1 API, here are the corresponding endpoints in the v2 API, along with the necessary modifications to achieve the same results.

❗️

Specifying the target account

The account_id param, previously available either in the query params or in the body, is removed from all methods. The account_id must now be consistently included in the path params.

List all emails

GET /v1/emails

• For Google and Outlook, use GET /v2/:account_id/emails List all Emails.
• ⚠️ For IMAP, Initial Sync must be enabled to use this route, otherwise use GET /v2/:account_id/folders/:folder_id/emails List folder Emails.
• Query param account_id is removed
  • Specify in the path param
• Query param folder is removed
  • Use GET /v2/:account_id/folders/:folder_id/emails List folder Emails to get emails from a specific folder
• Query param role is removed
  • Sync folders list on your side and use folder_id in List folder Emails
• Query param include_headers is removed
  • Headers are always present
• Response shape has changed (see Email object changes)

Send an email

POST /v1/email

• Use POST /v2/:account_id/emails/send Send an Email
• Content-Type have changed from multipart/form-data to application/json
• Body param reply_to changed
  • For Gmail and Outlook, this is the provider ID for the email message that you're replying to (id in the Email object). For IMAP, this is the RFC822 Message-ID header of the email message that you're replying to.
• Body param account_id is removed
  • Specify in the path param
• Body param attachmentshas changed
  • Specify an array of objects with filename, content_type and content as base64
• Body param body is removed
  • Use plain_text and html

Retrieve an email

GET /v1/emails/:email_id

• Use GET /v2/:account_id/emails/:email_id Get an Email
• Query param account_id is removed
  • Specify in the path param
• Query param include_headers is removed
  • Headers are always present
• Response shape has changed (see Email object changes)

Delete an email

DELETE /v1/emails/:email_id

• Use DELETE /v2/:account_id/emails/:email_id Trash an Email
• Query param account_id is removed
  • Specify in the path param
• Path param email_id changed
  • Use the id of the Email object

Update an email

PUT /v1/emails/:email_id

• Route is removed
  • Use POST /v2/:account_id/emails/:email_id/read Read an Email to mark email as read
  • Use POST /v2/:account_id/emails/:email_id/unread Unread an Email to mark email as unread
  • Use POST /v2/:account_id/emails/:email_id/modify Modify an Email to move folders, update labels, or set provider-specific properties
• Body param data (partial Mail object) is removed
  • Use folders_ids to move the email to specific folder(s)
  • Use specifics.{provider} for provider-specific properties (see below)
• Body param folders_ids is optional
  • Required for IMAP. If omitted, the email is not moved — useful when only updating provider-specific properties (e.g. categories)
• Body param categories moved to specifics.outlook.categories
  • Previously: { categories: ["Project X"] }
  • Now: { specifics: { outlook: { categories: ["Project X"] } } }
  • Same behavior: categories that don't exist yet in the account's master categories are automatically created with the color "None"
• Move and categories can now be combined in a single request
  • Previously required separate calls (move + updateMail)
  • Now: { folders_ids: ["folder_id"], specifics: { outlook: { categories: ["Urgent"] } } }

Retrieve an attachment from an email

GET /v1/emails/:email_id/attachments/:attachment_id

• Use GET /v2/:account_id/emails/:email_id/attachments/:attachment_id Get an Email Attachment
• Query param account_id is removed
  • Specify in the path param

List all folders

GET /v1/folders

• Use GET /v2/:account_id/folders List all Folders
• Query param account_id is removed
  • Specify in the path param
• Route is now paginated and don't return all folders
• Response shape has changed (see Folder object changes)

Retrieve a folder

GET /folders/:folder_id

• Use GET /v2/:account_id/folders/:folder_id Get a Folder
• Path param folder_id is changed
  • Use the id of the Folder object (must not be a Unipile ID)
• Query param account_id is removed
  • Specify in the path param
• Response shape has changed (see Folder object changes)

List all Contacts

GET /contacts

• Response shape has changed (see Contact object changes)

---

Email object changes

---

Folder object changed

Contact object changed