Let the platform do the work
SugarClubContact+1 (877) 842-7276

/Emails POST

Overview

Create a new Emails record.

Summary

Used for creating an archived email, creating a draft to send later, or creating and sending an email.

Creating an Archived Email

Request Arguments

Name Type Description Required
state String Use "Archived" to create an archived email. "Archived" is the default value if this argument is not provided. False
name String The email's subject. False
description_html String The email's HTML body. False
description String The email's plain text body. This field is not necessary unless the text body is different from the HTML body. False
raw_source String The complete raw source of the email showing the headers and content in one document. False
date_sent String The date that the email was sent/received. False
message_id String The email's unique identifier. False
message_uid String Only use this field for importing emails downloaded from an IMAP server, as this is the email's IMAP UID. False
assigned_user_id String The assigned user's ID. False
parent_type String The parent record's module. False
parent_id String The parent record's ID. False
team_name List List of teams that can access the email. False
from Object The email's sender. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about the sender is required to link the record.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the sender.
  • email_address_id is the ID of the email address the sender used to send the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
True
to Object The email's recipients found in the TO field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
cc Object The email's recipients found in the CC field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
bcc Object The email's recipients found in the BCC field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
attachments Object The email's attachments. Existing Notes records cannot be used as email attachments; only the create action is supported. Metadata about each attachment is required to link the records.
  • filename_guid is the temporary file ID for an uploaded file to attach as a Notes record.
  • upload_id is the ID of an existing file that the Notes record should reference as the attachment. This allows files to be shared by multiple Notes records, to preserve space.
  • When using upload_id, file_source should be provided to indicate from where the file originated. The value should be the module of the record that shares its ID with the file. So when an attachment comes from an email template, file_source should be EmailTemplates. And when an attachment comes from a document, file_source should be DocumentRevisions.
False
Request
{
  "state": "Archived",
  "name": "Re: Discuss Proposal",
  "description": "Now is a good time",
  "description_html": "<p>Now is a good time</p>",
  "date_sent": "2012-02-17T06:53:00-08:00",
  "message_id": "<d9c165d0-8863-ba61-dc85-51ed8016c476@example.com>",
  "assigned_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "parent_type": "Leads",
  "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6",
  "team_name": [{
    "id": "1",
    "display_name": "Global",
    "name": "Global",
    "name_2": "",
    "primary": true,
    "selected": false
  }],
  "from": {
    "create": [{
      "parent_type": "Leads",
      "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6"
    }]
  },
  "to": {
    "create": [{
      "parent_type": "Users",
      "parent_id": "9c61c46a-a7c5-df71-481c-51d48232f820"
    }]
  },
  "cc": {
    "create": [{
      "parent_type": "Contacts",
      "parent_id": "79b9c194-7d79-11e7-8fc5-3c15c2d582c6"
    }, {
      "parent_type": "Users",
      "parent_id": "79c2e800-7d79-11e7-84af-3c15c2d582c6"
      "email_address_id": "79cc341e-7d79-11e7-8748-3c15c2d582c6"
    }]
  },
  "bcc": {
    "create": [{
      "email_address_id": "ac804842-7d78-11e7-a809-3c15c2d582c6"
    }]
  },
  "attachments": {
    "create": [{
      "filename_guid": "afe9702e-53a3-0efb-6bbe-56c3580885ef",
      "name": "Quote.pdf",
      "filename": "Quote.pdf"
    }]
  }
}
Response
{
  "id": "a028341c-ba92-9343-55e7-56cf5beda121",
  "date_entered": "2016-02-25T11:53:07-08:00",
  "created_by": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "created_by_name": "Sarah Smith",
  "date_modified": "2016-02-25T11:53:07-08:00",
  "modified_by_name": "Sarah Smith",
  "modified_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "deleted": false,
  "assigned_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "assigned_user_name": "Sarah Smith",
  "state": "Archived",
  "name": "Re: Discuss Proposal",
  "description": "Now is a good time",
  "description_html": "<p>Now is a good time</p>",
  "date_sent": "2012-02-17T06:53:00-08:00",
  "message_id": "",
  "message_uid": "",
  "reply_to_status": false,
  "total_attachments": 1,
  "parent_name": "Tom Davis",
  "parent_type": "Leads",
  "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6"
  "team_count": "",
  "team_name": [{
    "id": 1,
    "name": "Global",
    "name_2": "",
    "primary": true,
    "selected": false
  }],
  "my_favorite": false,
  "_acl": {
    "fields": {}
  },
  "_module": "Emails"
}

Creating a Draft

Request Arguments

Name Type Description Required
state String Use "Draft" to save a draft. True
outbound_email_id String The ID of the chosen SMTP configuration for sending an email. Only use this field when saving a draft or sending an email. The user's default SMTP configuration is used if one hasn't been chosen prior to sending. False
name String The email's subject. False
description_html String The email's HTML body. False
description String The email's plain text body. This field is not necessary unless the text body is different from the HTML body. False
reply_to_id String Only use this field when saving a draft or sending an email that is a reply to another email. This is the ID of that other email. False
parent_type String The parent record's module. False
parent_id String The parent record's ID. False
to Object The email's recipients found in the TO field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
cc Object The email's recipients found in the CC field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
bcc Object The email's recipients found in the BCC field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
attachments Object The email's attachments. Existing Notes records cannot be used as email attachments; only the create action is supported. Metadata about each attachment is required to link the records.
  • filename_guid is the temporary file ID for an uploaded file to attach as a Notes record.
  • upload_id is the ID of an existing file that the Notes record should reference as the attachment. This allows files to be shared by multiple Notes records, to preserve space.
  • When using upload_id, file_source should be provided to indicate from where the file originated. The value should be the module of the record that shares its ID with the file. So when an attachment comes from an email template, file_source should be EmailTemplates. And when an attachment comes from a document, file_source should be DocumentRevisions.
False
Request
{
  "state": "Draft",
  "outbound_email_id": "b80adf1a-7d78-11e7-855a-3c15c2d582c6",
  "name": "Re: Discuss Proposal",
  "description_html": "<p>Calling you now.</p>",
  "reply_to_id": "a028341c-ba92-9343-55e7-56cf5beda121",
  "parent_type": "Leads",
  "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6",
  "to": {
    "create": [{
      "parent_type": "Leads",
      "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6"
    }]
  },
  "cc": {
    "create": [{
      "parent_type": "Contacts",
      "parent_id": "79b9c194-7d79-11e7-8fc5-3c15c2d582c6"
    }, {
      "parent_type": "Users",
      "parent_id": "79c2e800-7d79-11e7-84af-3c15c2d582c6"
      "email_address_id": "79cc341e-7d79-11e7-8748-3c15c2d582c6"
    }]
  },
  "bcc": {
    "create": [{
      "email_address_id": "ac804842-7d78-11e7-a809-3c15c2d582c6"
    }]
  },
  "attachments": {
    "create": [{
      "upload_id": "a028341c-ba92-9343-55e7-56cf5beda121",
      "name": "Contract.pdf",
      "filename": "Contract.pdf",
      "file_source": "DocumentRevisions"
    }, {
      "upload_id": "18a72782-4514-11e6-a5f7-3c15c2d582c6",
      "name": "survey.doc",
      "filename": "survey.doc",
      "file_source": "EmailTemplates"
    }]
  }
}
Response
{
  "id": "f3c85966-7d27-11e7-9e9e-3c15c2d582c6",
  "date_entered": "2016-02-25T11:53:07-08:00",
  "created_by": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "created_by_name": "Sarah Smith",
  "date_modified": "2016-02-25T11:53:07-08:00",
  "modified_by_name": "Sarah Smith",
  "modified_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "deleted": false,
  "assigned_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "assigned_user_name": "Sarah Smith",
  "state": "Draft",
  "outbound_email_id": "b80adf1a-7d78-11e7-855a-3c15c2d582c6",
  "name": "Re: Discuss Proposal",
  "description": "Now is a good time",
  "description_html": "<p>Now is a good time</p>",
  "date_sent": "2012-02-17T11:53:07-08:00",
  "message_id": "",
  "message_uid": "",
  "reply_to_id": "a028341c-ba92-9343-55e7-56cf5beda121",
  "reply_to_status": false,
  "total_attachments": 2,
  "parent_name": "Tom Davis",
  "parent_type": "Leads",
  "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6"
  "team_count": "",
  "team_name": [{
    "id": 1,
    "name": "Global",
    "name_2": "",
    "primary": true,
    "selected": false
  }],
  "my_favorite": false,
  "_acl": {
    "fields": {}
  },
  "_module": "Emails"
}

Sending an Email

Request Arguments

Name Type Description Required
state String Use "Ready" to send an email. True
outbound_email_id String The ID of the chosen SMTP configuration for sending an email. Only use this field when saving a draft or sending an email. The user's default SMTP configuration is used if one hasn't been chosen prior to sending. False
name String The email's subject. False
description_html String The email's HTML body. False
description String The email's plain text body. This field is not necessary unless the text body is different from the HTML body. False
reply_to_id String Only use this field when saving a draft or sending an email that is a reply to another email. This is the ID of that other email. False
parent_type String The parent record's module. False
parent_id String The parent record's ID. False
to Object The email's recipients found in the TO field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
cc Object The email's recipients found in the CC field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
bcc Object The email's recipients found in the BCC field. Existing EmailParticipants records cannot be used; only the create action is supported. Metadata about each recipient is required to link the records.
  • parent_type and parent_id can be Accounts, Contacts, Employees, Leads, Prospects, or Users, out out of the box. These fields are not necessary if only an email address is known for the recipient.
  • email_address_id is the ID of the email address the recipient used in the email. To get the ID of the email address, first make a request to /EmailAddresses POST. If this argument is not provided, then the primary email address of the parent record is used.
False
attachments Object The email's attachments. Existing Notes records cannot be used as email attachments; only the create action is supported. Metadata about each attachment is required to link the records.
  • filename_guid is the temporary file ID for an uploaded file to attach as a Notes record.
  • upload_id is the ID of an existing file that the Notes record should reference as the attachment. This allows files to be shared by multiple Notes records, to preserve space.
  • When using upload_id, file_source should be provided to indicate from where the file originated. The value should be the module of the record that shares its ID with the file. So when an attachment comes from an email template, file_source should be EmailTemplates. And when an attachment comes from a document, file_source should be DocumentRevisions.
False
Request
{
  "state": "Ready",
  "outbound_email_id": "b80adf1a-7d78-11e7-855a-3c15c2d582c6",
  "name": "Discuss Proposal",
  "description_html": "<p>When is a good time for us to chat?</p>",
  "parent_type": "Leads",
  "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6",
  "to": {
    "create": [{
      "parent_type": "Leads",
      "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6"
    }]
  },
  "cc": {
    "create": [{
      "parent_type": "Users",
      "parent_id": "79c2e800-7d79-11e7-84af-3c15c2d582c6"
      "email_address_id": "79cc341e-7d79-11e7-8748-3c15c2d582c6"
    }]
  },
  "attachments": {
    "create": [{
      "upload_id": "a028341c-ba92-9343-55e7-56cf5beda121",
      "name": "Contract.pdf",
      "filename": "Contract.pdf",
      "file_source": "DocumentRevisions"
    }, {
      "upload_id": "18a72782-4514-11e6-a5f7-3c15c2d582c6",
      "name": "survey.doc",
      "filename": "survey.doc",
      "file_source": "EmailTemplates"
    }]
  }
}
Response
{
  "id": "a7795664-7def-11e7-8add-3c15c2d582c6",
  "date_entered": "2016-02-25T08:53:07-08:00",
  "created_by": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "created_by_name": "Sarah Smith",
  "date_modified": "2016-02-25T08:53:07-08:00",
  "modified_by_name": "Sarah Smith",
  "modified_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "deleted": false,
  "assigned_user_id": "9c61c46a-a7c5-df71-481c-51d48232f820",
  "assigned_user_name": "Sarah Smith",
  "state": "Archived",
  "outbound_email_id": "b80adf1a-7d78-11e7-855a-3c15c2d582c6",
  "name": "Discuss Proposal",
  "description": "When is a good time for us to chat?",
  "description_html": "<p>When is a good time for us to chat?</p>",
  "date_sent": "2012-02-17T08:53:07-08:00",
  "message_id": "<a7795664-7def-11e7-8add-3c15c2d582c6@example.com>",
  "message_uid": "",
  "reply_to_id": "",
  "reply_to_status": false,
  "total_attachments": 2,
  "parent_name": "Tom Davis",
  "parent_type": "Leads",
  "parent_id": "f6a0611a-7d27-11e7-9d70-3c15c2d582c6"
  "team_count": "",
  "team_name": [{
    "id": 1,
    "name": "Global",
    "name_2": "",
    "primary": true,
    "selected": false
  }],
  "my_favorite": false,
  "_acl": {
    "fields": {}
  },
  "_module": "Emails"
}

Change Log

Version Change
v10 Added /Emails POST endpoint.