Sending with attachments

While sending with a template API or sending without a template API, file attachments can be included as part of the API request. To do so, add an array of attachment objects within the ‘attachments’ property of the API call. Each attachment object includes:

Property	Description
name	The filename shown to the receiver. eg. `invoice-352.pdf`
contentBlob	Base64-encoded string of file attachment content. Most programming langauges (Ruby, .NET, Java, PHP) will have built-in tools for this.
attachmentId	Waypoint Attachment ID when attaching large files.
contentType	MIME Type for the file attachment. eg. `application/pdf`
cid	Adding a CID (Content ID) will convert an attachment to an ‘inline attachment’. The CID is used as a reference ID for the inline attachment element.

Using standard attachments

A standard email attachment is a file included with an email but not displayed within the body of the message. Common examples include PDFs or spreadsheets. Recipients must download or open the file separately.

To add attachments to emails on Waypoint, simply add an attachments object on each API call.

Emails using standard attachments must be under 5 MB (including email body content). Learn how to attach larger files.

Code example

const axios = require('axios');
const fs = require('fs');

// Read and encode the file to base64
const filePath = './order-receipt.pdf';
const fileContent = fs.readFileSync(filePath);
const base64Content = fileContent.toString('base64');

// Send the email with attachment
axios({
  method: "post",
  url: "https://live.waypointapi.com/v1/email_messages",
  headers: {
    "Content-Type": "application/json"
  },
  auth: {
    username: API_KEY_USERNAME,
    password: API_KEY_PASSWORD
  },
  data: {
    "templateId": "wptemplate_ABc123XYZ",
    "to": "jordan@usewaypoint.com",
    "variables": {
      "user": {
        "displayName": "Jordan",
      },
      "product": {
        "title": "Beechers Mac & Cheese",
        "id": "02934203942"
      }
    },
    "attachments": [
      {
        "name": `order-receipt.pdf`,
        "contentBlob": base64Content,
        "contentType": 'application/pdf',
      },
    ],
  }
})
.then(function (response) {
  console.log(response);
})
.catch(function (error) {
  console.log(error);
})

Using large attachments

Since standard attachments are capped at 5 MB, this can be too limiting for larger files like custom reports, presentations, detailed invoices, or other high-quality assets.

For these cases, we provide a dedicated API flow for large attachments. Growth customers can send emails with attachments up to 10 MB, and Pro customers up to 20 MB.

The process works like this:

POST to v1/attachments API to create an attachment that returns an uploadURL and an attachment id.
PUT to uploadUrl to upload your file.
POST to v1/email_messages API to send your email. Include the attachment id in your data attachments array.

View the code example below for details.

Code example

import axios from 'axios';
import fs from 'fs';

// File to upload
const FILE_PATH = './reports/report-00000001.pdf';

async function executeUpload() {
  const file = fs.createReadStream(FILE_PATH);
  const stats = fs.statSync(FILE_PATH);

  // Create attachment URL
  const { data } = await axios({
    method: 'post',
    url: 'https://live.waypointapi.com/v1/attachments',
    headers: {
      'Content-Type': 'application/json',
    },
    auth: {
      username: API_KEY_USERNAME,
      password: API_KEY_PASSWORD,
    },
  });

  const presignedUrl = data.data.uploadUrl;
  const attachmentId = data.data.id;
  console.log('Attachment created:', { attachmentId, presignedUrl });

  // Upload file to the upload URL with file content type and file size
  await axios.put(presignedUrl, file, {
    headers: {
      'Content-Type': 'application/pdf',
      'Content-Length': stats.size.toString(),
    },
  });

  // Send email with attachment ID, name, and file content type
  const emailMessageRes = await axios({
    method: 'post',
    url: 'https://live.waypointapi.com/v1/email_messages',
    headers: {
      'Content-Type': 'application/json',
    },
    auth: {
      username: API_KEY_USERNAME,
      password: API_KEY_PASSWORD,
    },
    data: {
      to: 'jordan@usewaypoint.com',
      from: 'support@usewaypoint.com',
      bodyHtml: '<p>Your report is attached.</p>',
      subject: 'Your Report',
      attachments: [
        {
          attachmentId: attachmentId,
          name: 'report-00000001.pdf',
          contentType: 'application/pdf',
        },
      ],
    },
  });
  console.log('Email message created:', emailMessageRes.data);
}

executeUpload();

Limitations

Using large attachments require Growth or Pro plans.

File size limits by plan:

Free and Starter: Unavailable
Growth: 10 MB
Pro: 20 MB

Using inline attachments

An inline attachment is a file, usually an image, that is embedded directly within the email content. It’s displayed as part of the message body, making it feel like a seamless visual element of the email.

Inline attachments work similarly to standard attachments, but with one key difference: each attachment includes a cid (Content-ID) parameter. This cid is used to reference the attachment within the bodyHtml, allowing it to be displayed inline as part of the email content.

In the example below, note the "cid": "emoji" being referenced in the <img src=\"cid:emoji\" />.

Code example

axios({
  "to": "Jordan Tester <jordan@usewaypoint.com>",
  "from": "Waypoint Support <support@usewaypoint.com>",
  "bodyHtml": "<h1>Hello from Waypoint <img src=\"cid:emoji\" /></h1>",
  "subject": "Hello from Waypoint",
  "attachments": [{
    "name": "emoji.png",
    "cid": "emoji",
    "contentType": "image/png",
    "contentBlob": "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAApgAAAKYB3X3/OAAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAANCSURBVEiJtZZPbBtFFMZ/M7ubXdtdb1xSFyeilBapySVU8h8OoFaooFSqiihIVIpQBKci6KEg9Q6H9kovIHoCIVQJJCKE1ENFjnAgcaSGC6rEnxBwA04Tx43t2FnvDAfjkNibxgHxnWb2e/u992bee7tCa00YFsffekFY+nUzFtjW0LrvjRXrCDIAaPLlW0nHL0SsZtVoaF98mLrx3pdhOqLtYPHChahZcYYO7KvPFxvRl5XPp1sN3adWiD1ZAqD6XYK1b/dvE5IWryTt2udLFedwc1+9kLp+vbbpoDh+6TklxBeAi9TL0taeWpdmZzQDry0AcO+jQ12RyohqqoYoo8RDwJrU+qXkjWtfi8Xxt58BdQuwQs9qC/afLwCw8tnQbqYAPsgxE1S6F3EAIXux2oQFKm0ihMsOF71dHYx+f3NND68ghCu1YIoePPQN1pGRABkJ6Bus96CutRZMydTl+TvuiRW1m3n0eDl0vRPcEysqdXn+jsQPsrHMquGeXEaY4Yk4wxWcY5V/9scqOMOVUFthatyTy8QyqwZ+kDURKoMWxNKr2EeqVKcTNOajqKoBgOE28U4tdQl5p5bwCw7BWquaZSzAPlwjlithJtp3pTImSqQRrb2Z8PHGigD4RZuNX6JYj6wj7O4TFLbCO/Mn/m8R+h6rYSUb3ekokRY6f/YukArN979jcW+V/S8g0eT/N3VN3kTqWbQ428m9/8k0P/1aIhF36PccEl6EhOcAUCrXKZXXWS3XKd2vc/TRBG9O5ELC17MmWubD2nKhUKZa26Ba2+D3P+4/MNCFwg59oWVeYhkzgN/JDR8deKBoD7Y+ljEjGZ0sosXVTvbc6RHirr2reNy1OXd6pJsQ+gqjk8VWFYmHrwBzW/n+uMPFiRwHB2I7ih8ciHFxIkd/3Omk5tCDV1t+2nNu5sxxpDFNx+huNhVT3/zMDz8usXC3ddaHBj1GHj/As08fwTS7Kt1HBTmyN29vdwAw+/wbwLVOJ3uAD1wi/dUH7Qei66PfyuRj4Ik9is+hglfbkbfR3cnZm7chlUWLdwmprtCohX4HUtlOcQjLYCu+fzGJH2QRKvP3UNz8bWk1qMxjGTOMThZ3kvgLI5AzFfo379UAAAAASUVORK5CYII="
  }]
})
.then(function (response) {
  console.log(response);
})
.catch(function (error) {
  console.log(error);
})

Activity logs

Within your Activity, if you view a message log that was sent with one or many attachments, they will the filenames will show up underneath the message preview.

Logs only show the attachment filename (even for inline attachments), the full content of the attachment is not stored on Waypoint.

Waypoint Attachment

Limitations

Messages have size limitations. On our Free and Starter plan, the max total size of the email (including attachments) is 2mb. On our Growth and Pro plans, the max total size is 5mb.
Attachments are currently not supported by email batch sending
Attachments with following file extensions are not supported and will cause the email to not be sent: .ade, .adp, .app, .asp, .bas, .bat, .cer, .chm, .cmd, .com, .cpl, .crt, .csh, .der, .exe, .fxp, .gadget, .hlp, .hta, .inf, .ins, .isp, .its, .js, .jse, .ksh, .lib, .lnk, .mad, .maf, .mag, .mam, .maq, .mar, .mas, .mat, .mau, .mav, .maw, .mda, .mdb, .mde, .mdt, .mdw, .mdz, .msc, .msh, .msh1, .msh2, .mshxml, .msh1xml, .msh2xml, .msi, .msp, .mst, .ops, .pcd, .pif, .plg, .prf, .prg, .reg, .scf, .scr, .sct, .shb, .shs, .sys, .ps1, .ps1xml, .ps2, .ps2xml, .psc1, .psc2, .tmp, .url, .vb, .vbe, .vbs, .vps, .vsmacros, .vss, .vst, .vsw, .vxd, .ws, .wsc, .wsf, .wsh, .xnk.