How to send emails with file attachments using Mailgun API

Other Questions Mailgun
1

I’m trying to send emails through Mailgun that include file attachments but I’m running into problems. The emails are delivered successfully but the attachments never come through. When I try using file paths, they just show up as text in the email instead of actual attached files.

Has anyone successfully implemented file attachments with Mailgun? Here’s what I’ve been working with:

$api_key = 'key-8bx7ynkq40ke7gdt5hd484thwkyufpm1';
$api_version = 'api.mailgun.net/v3/';
$domain_name = "example.mailgun.org";
$sender_email = "[email protected]";
$response_email = "[email protected]";

$message_endpoint = "https://".$api_version.$domain_name."/messages";

$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl_handle, CURLOPT_MAXREDIRS, 5);
curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl_handle, CURLOPT_VERBOSE, false);
curl_setopt($curl_handle, CURLOPT_HEADER, false);
curl_setopt($curl_handle, CURLOPT_TIMEOUT, 30);
curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, false);

curl_setopt($curl_handle, CURLOPT_USERPWD, 'api:' . $api_key);
curl_setopt($curl_handle, CURLOPT_POST, true);
curl_setopt($curl_handle, CURLOPT_URL, $message_endpoint);

$email_data = array(
    'from' => 'Support Team <' . $sender_email . '>',
    'to' => '[email protected]',
    'h:Reply-To' => $response_email,
    'subject' => 'Document Delivery ' . date('Y-m-d'),
    'html' => 'Please find your requested document attached.',
    'attachment[0]' => 'document.zip'
);

curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $email_data);

$response = curl_exec($curl_handle);
curl_close($curl_handle);

$decoded_response = json_decode($response, true);
var_dump($decoded_response);

I’m using my actual Mailgun credentials of course. What am I doing wrong with the attachment handling?

2

You’re passing just the filename ‘document.zip’ as a string instead of actually referencing the file. That’s why it’s not working. For PHP 5.5+, use CURLFile - it’s more secure than the old @ prefix method: $email_data = array(‘from’ => ‘Support Team <’ . $sender_email . ‘>’, ‘to’ => ‘[email protected]’, ‘h:Reply-To’ => $response_email, ‘subject’ => ‘Document Delivery ’ . date(‘Y-m-d’), ‘html’ => ‘Please find your requested document attached.’, ‘attachment[0]’ => new CURLFile(’/absolute/path/to/document.zip’, ‘application/zip’, ‘document.zip’)); Make sure you’re using the full absolute path and check that PHP can actually read the file (permissions matter). I’ve done this with PDFs, images, and zip files through Mailgun - works great once you get the path right.

3

check your file permissions - I hit the same issue where Mailgun couldn’t access the file even tho my CurlFile syntax was right. try chmod 644 on the zip and make sure your web server user can read the directory path. also test with a small txt file first to rule out file type probs.

4

The Problem:

You’re attempting to send email attachments via Mailgun using PHP’s curl, but the attachments aren’t arriving. The email itself delivers, but the attachments are rendered as text within the email body. Your current approach uses a simple filename string for attachment specification, which is incorrect.

:thinking: Understanding the “Why” (The Root Cause):

Mailgun’s API requires a proper file handle, not just the filename, to correctly process file attachments. Passing a filename string ('document.zip') only sends the string itself, not the actual file’s data. This fundamental misunderstanding is why your attachments fail to arrive as intended. Directly referencing the file using methods like CURLFile (for PHP 5.5+) or curl_file_create() ensures Mailgun receives the file’s content.

:gear: Step-by-Step Guide:

  1. Replace the Attachment Handling: The core issue lies in how you’re specifying the attachment. Instead of 'attachment[0]' => 'document.zip', you need to use a function that correctly handles file uploads. For PHP versions 5.5 and above, use CURLFile:

    $email_data = array(
    'from' => 'Support Team <' . $sender_email . '>',
    'to' => '[email protected]',
    'h:Reply-To' => $response_email,
    'subject' => 'Document Delivery ' . date('Y-m-d'),
    'html' => 'Please find your requested document attached.',
    'attachment[0]' => new CURLFile('/absolute/path/to/document.zip', 'application/zip', 'document.zip')
);

    Replace /absolute/path/to/document.zip with the full absolute path to your document.zip file on your server. For example: /var/www/html/attachments/document.zip. The second argument ('application/zip') specifies the MIME type; adjust it according to your file type (e.g., 'application/pdf' for PDFs, 'image/jpeg' for JPGs). The third argument is the filename as it will appear in the recipient’s email.

    For PHP versions below 5.5, use curl_file_create():

    $email_data = array(
  // ... other data ...
  'attachment[0]' => curl_file_create('/absolute/path/to/document.zip', 'application/zip', 'document.zip')
);

  2. Verify File Permissions: Ensure your web server user (e.g., www-data, apache) has read access to the file and its parent directory. Use the chmod command in your terminal to adjust permissions if necessary: chmod 644 /absolute/path/to/document.zip. If you’re still having trouble, try chmod 755 on the directory containing the attachment.

  3. Test with a Small File: Before sending large files, test with a small text file to rule out file size or type-specific issues. This simplifies debugging.

  4. Check Mailgun Limits: Mailgun has attachment size limits. If your file is too large, it will fail silently. Ensure your attachment is within Mailgun’s allowed size limit (check your Mailgun account for this, it is usually 25MB per message).

:mag: Common Pitfalls & What to Check Next:

  • Incorrect File Path: Double and triple-check that the file path in your CURLFile or curl_file_create() call is absolutely correct. Typos are common here.
  • File Existence: Verify that the file actually exists at the specified path using a simple PHP check (e.g., file_exists('/absolute/path/to/document.zip')).
  • MIME Type: Make sure you’re using the correct MIME type for your attachment. An incorrect MIME type can prevent the attachment from rendering correctly.
  • Mailgun API Keys & Configuration: Ensure your Mailgun API key and domain are correctly set in your code.

:speech_balloon: Still running into issues? Share your (sanitized) config files, the exact command you ran, and any other relevant details. The community is here to help!

5

The issue is definitely how you’re handling the file reference. I hit this exact problem last year with our Mailgun document delivery system. What fixed it for me was curl_file_create() - basically the same as CURLFile but more explicit. Here’s the fix for your attachment line:

'attachment[0]' => curl_file_create('/path/to/document.zip', 'application/zip', 'document.zip')

Relative paths don’t work reliably here - you need the full server path. Also, if you’re sending multiple attachments, watch out for Mailgun’s 25MB limit per message. I learned this the hard way trying to send large reports. The error messages don’t always tell you it’s a size issue, so check your file sizes first.

6

add an @ symbol b4 the file path - that’s how Mailgun knows it’s a file attachment. change it to 'attachment[0]' => '@/full/path/to/document.zip' instead of just the filename. also double-check the file exists on ur server and php can read it.

7

This topic was automatically closed 24 hours after the last reply. New replies are no longer allowed.