MailSlurp Attachment API: Send & Download Attachments in Code or Tests

MailSlurp offers an email attachment API so you can send and receive attachments in code or tests without a mailserver. Most actions use the /attachments/ endpoints. See the AttachmentController for method documentation.

How attachments in emails work

The SMTP specification for email messaging lays out many official headers and properties of an email. It is however not very specific about attachments. Using the MIME spec, an email and its attachments are transfered using a string multipart messagethat is base64 encoded as 7-bit ASCII text. MailSlurp makes attachment encoding easy.

MailSlurp attachment processes

Attachments can be sent and received in tests and code or using the MailSlurp dashboard. Create a free account to get started.

Send attachments with emails

Before you send an attachment first upload it in the dashboard. This will take care of the MIME encoding etc.

You can do the same in code using the AttachmentController uploadAttachment endpoint. Take a file convert it into a Base64 encoded string. POST it to the endpoint and it will return an array whose first element is the ID of the uploaded attachment.

PHP example

Here is an example of uploading an attachment in PHP:

private function uploadAttachment(): array
{
    // a path to some file you want to attach
    $pathToAttachment = $this->pathToAttachment;

    // read file contents
    $contents = file_get_contents($pathToAttachment);

    // encode the file contents to a base64 encoded string for uploading
    $base64Contents = base64_encode($contents);

    // extract file name from path
    $filename = basename($pathToAttachment);
    
    // get the mime type from the file name
    $contentType =  mime_content_type($filename);

    // set upload options
    $uploadOptions = new MailSlurpModelsUploadAttachmentOptions();
    $uploadOptions->setFilename($filename);
    $uploadOptions->setContentType($contentType);
    $uploadOptions->setBase64Contents($base64Contents);

    // now upload using attachment controller
    $attachmentController = new MailSlurpApisAttachmentControllerApi(null, $this->config);

    // returns [$attachmentId]
    return $attachmentController->uploadAttachment($uploadOptions);
}

NodeJS example

The same methods apply for other languages. Here is the same example of base64 encoding a file in Javascript:

/**
 * Upload base 64 encoded file
 * Return array containing attachment ID as first element
 * @returns {Promise<string[]>}
 */
async function uploadAttachment() {
    const fileBase64Encoded = await readFile(pathToAttachment, { encoding: 'base64' });
    const attachmentController = new MailSlurp(config).attachmentController;

    return attachmentController.uploadAttachment({
        base64Contents: fileBase64Encoded,
        contentType: 'text/plain',
        filename: basename(pathToAttachment)
    })
}

Attachment size limits

The MIME email standard does not specify a limit to attachments. See the email attachment size limits guide for more information.

Receive and download attachments

Attachments that are sent to MailSlurp mailboxes are stored and are available by ID. They can be viewed in the dashboard or using the API.

Waiting for emails to arrive

You can wait for an expected emails using the WaitForEmailController. Retrieve an email to view the attachment IDS.

Download attachments by ID

Call the downloadAttachmentAsBase64Encoded to download an attachment as a base 64 encoded string. This makes consuming binary content easier for some clients. Base64 decode the content string to a byte array to access the file. This example uses the NodeJS library.

async function canReceiveAttachment(inboxId) {
  const waitForController = new MailSlurp(config).waitController;

  const email = await waitForController.waitForLatestEmail(inboxId, 60000, true)

  expect(email.attachments.length).toEqual(1);

  const emailController = new MailSlurp(config).emailController
  const attachmentDto = await emailController.downloadAttachmentBase64(email.attachments[0], email.id)

  expect(attachmentDto.base64FileContents).toBeTruthy()
  expect(attachmentDto.sizeBytes).toBeTruthy()
  expect(attachmentDto.contentType).toBeTruthy()
}

You can also call the downloadAttachmentAsBytes method and MailSlurp returns an octet-stream of bytes in response. These can be streamed to disk or a buffer and read later.