Attachments

When you want to send files through the API, such as when using the Create draft or similar API endpoints, you must set the Content-Type HTTP header set to multipart/form-data. You then split the JSON data that you normally send in the request body into multiple form fields (one for each property) named after the property key.

Many but not all Core API endpoints support sending attachments. Refer to the Core API Reference documentation for details.

Basic example: make sure the Content-Type header is set to multipart/form-data

curl -X POST 'https://api2.frontapp.com/inboxes/inb_123/imported_messages' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: multipart/form-data' \
--form 'external_id=123456abcdef' \
--form 'created_at=1619656054' \
--form 'attachments[]=@/Users/me/Photos/cat.jpg' \

Arrays in multipart form data

Some API body parameters must be sent as an array. For example, the to parameter or the attachments array itself. In these cases, you split the array into multiple form fields. For example, {"to": [[email protected], [email protected]]} would be split in two fields named to[][email protected] and to[][email protected]).

curl -X POST 'https://api2.frontapp.com/channels/FRONT_CHANNEL_ID/messages' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: multipart/form-data' \
--form 'author_id=AUTHOR_ID' \
--form 'to[][email protected]' \
--form 'to[][email protected]' \
--form 'attachments[]=@/Users/me/Photos/cat.jpg' \
--form 'attachments[]=@/Users/me/Photos/dog.jpg' \
--form 'body=MESSAGE_BODY'

Nested objects in multipart form data

Some API body parameters are nested within objects, such as name and handle in the sender object:

"sender": {
  "name": "Lucy",
  "handle": "[email protected]"
}

In these cases, split the parameters into multiple form fields and use the syntax, objectName[propertyName] for the name of the form field. In our sender example, the fields would be named sender[handle] and sender[name].

curl -X POST 'https://api2.frontapp.com/inboxes/inb_123/imported_messages' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: multipart/form-data' \
--form 'external_id=lj19hkjjlsd9893d' \
--form 'created_at=1619656054' \
--form 'sender[handle][email protected]' \
--form 'sender[name]=Lucy' \
--form 'metadata[is_inbound]=true' \
--form 'metadata[is_archived]=false' \
--form 'to[][email protected]' \
--form 'to[][email protected]' \
--form 'body=MESSAGE_BODY' \
--form 'attachments[]=@/Users/me/Photos/cat.jpg' \
--form 'attachments[]=@/Users/me/Photos/dog.jpg'

Node examples

The following provides an example for Node. We also have examples in GitHub for sending an attachment when creating a new message and for receiving messages in a custom channel.

const FRONT_API_TOKEN = 'YOUR FRONT API TOKEN GOES HERE';
const CHANNEL_ID = 'YOUR FRONT CHANNEL ID GOES HERE';

const FormData = require('form-data');
const fs = require('fs');

// abstract and promisify actual network request
async function makeRequest(formData, options) {
  return new Promise((resolve, reject) => {
    const req = formData.submit(options, (err, res) => {
      if (err)
        return reject(new Error(err.message))

      if (res.statusCode < 200 || res.statusCode > 299)
        return reject(new Error(`HTTP status code ${res.statusCode}`))

      const body = [];
      res.on('data', (chunk) => body.push(chunk));
      res.on('end', () => {
        const resString = Buffer.concat(body).toString();
        resolve(resString);
      })
    })
  })
}

const formData = new FormData()

// Set your data here: (See full options at https://dev.frontapp.com/reference/messages-1#post_channels-channel-id-messages)
formData.append('subject', 'Message subject');
formData.append('to[]', '[email protected]');
formData.append('to[]', '[email protected]');
formData.append('sender_name', 'Support');
formData.append('body', '<p>Message body</p>');
formData.append('attachments[]', fs.createReadStream('./photo.jpg'));

const options = {
  host: 'api2.frontapp.com',
  path: `/channels/${CHANNEL_ID}/messages`,
  method: 'POST',
  protocol: 'https:', // note : in the end
  headers: {
    Authorization: `Bearer ${FRONT_API_TOKEN}`
  },
}

async function run() {
  const res = await makeRequest(formData, options);
  console.log(res);
}

run()

Download an attachment from the API

For information about downloading attachments received in API responses, refer to the reference topic and the Download attachment endpoint.