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}} <help@example.com>

For example if the machine user's public name was Acme Refunds:

Acme Refunds <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",
          "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 with "Re:" prepended.
• 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",
          "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
    }
  }
}

---

If you have any problems, please get in touch with us by email on help@plain.com, and we will be happy to help.