Skip to main content

Sending and replying to emails

info

This recipe assumes you've already familiarized yourself with the Core API getting started , Authentication, and Error Handling pages.

Overview

There are two mutations to send emails to customers:

  1. sendNewEmail: Sends a new email to a customer. This is a new email thread, so you can provide the subject of the email using this mutation. (sendNewEmail reference)
  2. replyToEmail: Replies to an existing email in the customer's timeline. As input, you must give a previous email ID and you can't provide the subject (it will be created for you like: "Re: previous subject"). (replyToEmail reference)

Both mutations require you to have an existing customer created in Plain. You can use the Upserting a customer recipe to create one.

Other input fields:

  • subject: The subject line of the email
  • textContent: The plain text content of the email. Currently Plain doesn't support rich formatting of emails, so this content will be sent as is.
  • additionalRecipients: An array of CC-d recipients (object of email and an optional name)
  • hiddenRecipients: An array of BCC-d recipients (object of email and an optional name)
  • attachmentIds: An array of uploaded attachments IDs to send with the email.

From: field

When sending an email using an API Key (i.e. as a Machine User) the email's From: field will be composed according to the following rule:

{{Machine User's Public Name}} at {{Workspace's Public Name}} <help@example.com>

For example:

Refunds at Acme Co. <help@acme.com>

Permissions

The sendNewEmail and replyToEmail mutations require the following permission: email:create

Sending a new email

Mutation

The GraphQL mutation is the following:

mutation sendNewEmail($input: SendNewEmailInput!) {
sendNewEmail(input: $input) {
email {
id
inReplyToEmailId
from {
name
email
}
to {
name
email
}
subject
textContent
additionalRecipients {
name
email
}
hiddenRecipients {
name
email
}
createdAt {
iso8601
}
}
error {
message
type
code
fields {
field
message
type
}
}
}
}
note

The Email Object has more fields you can select, but in this recipe we're only selecting a few important ones.

Variables

caution

Remember to replace c_XXXXXXXXXXXXXXXXXXXXXXXXXX with an existing customer's ID.

{
"input": {
"customerId": "c_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"subject": "Contacting you about your day",
"textContent": "Hi there,\nHow are you today?\n\nThanks,\nYour friendly Customer Support",
"additionalRecipients": [
{
"name": "CC'd person",
"email": "cc-d-person@example.com"
}
],
"hiddenRecipients": [
{
"name": "BCC'd person",
"email": "bcc-d-person@example.com"
}
]
}
}

Response

{
"data": {
"sendNewEmail": {
"email": {
"id": "em_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"inReplyToEmailId": null,
"from": {
"name": "Machine User Public Name at Workspace Public Name",
"email": "help@demo.plain-demo.com"
},
"to": {
"name": "Customer",
"email": "customer@example.com"
},
"subject": "Contacting you about your day",
"textContent": "Hi there,\nHow are you today?\n\nThanks,\nYour friendly Customer Support",
"additionalRecipients": [
{
"name": "CC'd person",
"email": "cc-d-person@example.com"
}
],
"hiddenRecipients": [
{
"name": "BCC'd person",
"email": "bcc-d-person@example.com"
}
],
"createdAt": {
"iso8601": "2022-08-31T11:55:45.848Z"
}
},
"error": null
}
}
}

Replying to an email

Mutation

The GraphQL mutation is the following:

mutation replyToEmail($input: ReplyToEmailInput!) {
replyToEmail(input: $input) {
email {
id
inReplyToEmailId
from {
name
email
}
to {
name
email
}
subject
textContent
additionalRecipients {
name
email
}
hiddenRecipients {
name
email
}
createdAt {
iso8601
}
}
error {
message
type
code
fields {
field
message
type
}
}
}
}
note

The Email Object has more fields you can select, but in this recipe we're only selecting a few important ones.

Variables

caution

Remember to replace c_XXXXXXXXXXXXXXXXXXXXXXXXXX with an existing customer's ID and em_XXXXXXXXXXXXXXXXXXXXXXXXXX with an existing email's ID

In this input:

  • A subject can't be provided, it will automatically use the previous email's subject and prepend a "Re:"
  • inReplyToEmailId must be provided
{
"input": {
"customerId": "c_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"inReplyToEmailId": "em_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"textContent": "Hello there,\nThis is a reply to your previous email.\nThanks,\nYour friendly Customer Support",
"additionalRecipients": [
{
"name": "CC'd person",
"email": "cc-d-person@example.com"
}
],
"hiddenRecipients": [
{
"name": "BCC'd person",
"email": "bcc-d-person@example.com"
}
]
}
}

Response

{
"data": {
"replyToEmail": {
"email": {
"id": "em_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"inReplyToEmailId": "em_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"from": {
"name": "Machine User Public Name at Workspace Public Name",
"email": "help@demo.plain-demo.com"
},
"to": {
"name": "Customer",
"email": "customer@example.com"
},
"subject": "Re: Contacting you about your day",
"textContent": "Hello there,\nThis is a reply to your previous email.\nThanks,\nYour friendly Customer Support",
"additionalRecipients": [
{
"name": "CC'd person",
"email": "cc-d-person@example.com"
}
],
"hiddenRecipients": [
{
"name": "BCC'd person",
"email": "bcc-d-person@example.com"
}
],
"createdAt": {
"iso8601": "2022-08-31T14:32:28.331Z"
}
},
"error": null
}
}
}