Redirecting Users After Contact Form 7 Submission
When building a dynamic web application, you often need to trigger actions immediately after a user submits data. A common requirement is to provide a downloadable resourceâlike a PDF guide or invoiceâright after form submission. In WordPress, Contact Form 7 (CF7) handles this via the on_sent_ok parameter in the mail tab settings. However, simply setting a redirect URL often leads to the dreaded "There was an error trying to send your message" notice, even if the file itself is valid and accessible.
The core issue lies in how WordPress processes the form submission versus how it handles redirects. When you define on_sent_ok: "location = 'http://localhost/wordpress/wp-content/uploads/2017/08/pdf-sample.pdf';", you are instructing CF7 to redirect the browser immediately after the form data is processed. However, this mechanism relies on the server successfully sending the email (or dummy mail if no recipient is set) before executing the redirect logic. If the mail subsystem failsâeven with a mock recipientâthe standard CF7 error handler triggers an abort sequence that prevents the location header from being sent properly, resulting in the generic error message.
To achieve the desired behavior where a PDF downloads automatically upon submission, you must bypass the email sending requirement or handle the redirect logic within the server-side environment rather than relying solely on the client-side on_sent_ok string. Here is how to implement this robustly.
Implementing the Redirect in CF7 Settings
The most straightforward approach involves ensuring the mailer doesn't fail before the redirect can occur. If your form does not actually need to send an email, you should set the "To" field in the Mail tab to something like admin@example.com or a null string, depending on your specific mailer plugin configuration. This prevents the "sending message" error from firing.
Once the mail step is neutralized, update your Additional Settings to include a direct redirect:
on_sent_ok: "location = 'http://yourdomain.com/wp-content/uploads/2017/08/pdf-sample.pdf';"
Crucial Implementation Detail: You must replace http://localhost with your actual domain name (e.g., https://yoursite.com). Using localhost in production or shared environments will cause a 403 Forbidden or 404 Not Found error because the web server serving WordPress is not running on the loopback interface of the user's machine. The redirect URL must be an absolute, publicly accessible path.
Handling File Downloads via JavaScript
If you prefer to keep the form submission intact without relying on server-side redirects (which can sometimes feel jarring to users), a more modern approach uses JavaScript to intercept the success event. This allows you to trigger a download programmatically while keeping the user on the same page if desired, or redirecting them gracefully.
You can achieve this by adding the following code to your theme's functions.php file or a custom plugin:
add_action( 'wpcf7_submitted_form', function ( $contact_form ) {
// Ensure we are on the frontend and not an admin screen
if ( ! is_admin() && isset($_POST['your-name']) ) {
// Redirect to the PDF file
wp_redirect( home_url( '/wp-content/uploads/2017/08/pdf-sample.pdf' ), 302 );
exit;
}
} );
This hook fires only after the form is successfully processed. By using wp_redirect and exit, you ensure that no further output is buffered, which prevents conflicts with CF7's own redirect handling. The response code 302 explicitly tells the browser to fetch the new URL.
Trade-offs and Considerations
When choosing between server-side redirects (via on_sent_ok) and programmatic hooks (wpcf7_submitted_form), consider the user experience. A hard redirect moves the user immediately, which is efficient but offers no chance to display a success message first. The JavaScript or PHP hook approach gives you flexibility; you could theoretically log the submission in your database before sending them to the file.
Additionally, ensure the PDF file has the correct MIME type (application/pdf) set in the server configuration (e.g., .htaccess for Apache) so the browser treats it as a download rather than attempting to render it inline. If you are using Nginx or another server stack, verify that the types mapping is correctly configured for PDFs.
For developers looking to streamline this workflow further, integrating Contact Form 7 with a backend framework like Laravel can provide more granular control over file handling and redirection logic. Platforms such as LaravelCompany offer resources on how to extend CF7 functionality using Laravel's event system, allowing you to decouple the form submission entirely from the download action for better scalability.