SendGrid Gzip Email Compression: A Step-by-Step Guide

Efficiently manage high-volume email sends with SendGrid. The platform supports gzip compression for enhanced customer experience, and allows for lighter and faster mail transmission. Below is a comprehensive guide to help you navigate this feature with ease.


  • A registered SendGrid account.
  • Your exclusive SendGrid API Key.
  • Fundamental acquaintance with JSON structure.
  • Gzip Compression activated on your SendGrid account (Contact our Support Team to see if you are eligible for enablement of this feature).
  • Familiarity with our Documentation on using Gzip in an API call Mail Send Gzip.


Step 1: Create JSON Payload

To start with, you need an Email in JSON format that you want to send. Here is a basic template for your perusal:

"personalizations": [
"to": [
"email": ""
"subject": "Your Subject Here!"
"from": {
"email": ""
"content": [
"type": "text/plain",
"value": "Your text-based message here!"

Modify this template per your requirements and save this file as `payload.json`.


Step 2: Compress the JSON File Using Gzip

The next step is to create a gzip compressed version of your original payload. Numerous tools are available on almost all operating systems that let you create gzip files.

  • Find your `payload.json` file using File Explorer/Finder.
  • Right-click on it and choose `Create Archive` or similar option depending upon your operating system.
  • In the file type select dropdown, choose `.gz` option and click on `Create`.

This should give you a new file named `payload.json.gz`.


Mac users can compress files using the built-in Terminal application. Here's how:

1. Open Terminal: By either searching for it in Spotlight (Command + Space) or finding it in Applications > Utilities > Terminal.

2. Navigate to Your File Directory:  Use `cd` command to navigate to the folder where your `payload.json` is located. For example, if your file is on the Desktop, you could use:

cd ~/Desktop

3. Compress JSON File Using Gzip: Enter the following command to create a Gzip compressed version of your `payload.json`:

gzip -c payload.json > payload.json.gz

This will create a file called `payload.json.gz` in the same directory as your original file. The `-c` flag is used here to write on the standard output but keep original files unchanged.

To verify that everything worked correctly, you should see `payload.json.gz` file in your directory along with the original `payload.json`.


Step 3: Prepare Curl Command

The next step is to set up our curl request for sending the mail:

curl --request POST \
--url \
--header 'Authorization: Bearer SENDGRID_API_KEY' \
--header 'Content-Encoding: gzip' \
--header 'Content-Type: application/json' \
--data-binary "@<path to your/payload.json.gz>"

Replace `SENDGRID_API_KEY` with your actual SendGrid API key. Also, replace <path to your/payload.json.gz> with the exact path on your machine where the gzip file is located.


Step 4: Execute Curl Command

Finally, we are ready to send our email.

  • Open Terminal.
  • Copy and paste the prepared curl command into Terminal.
  • Press `Enter` to execute the command.

You should now have successfully sent an email using SendGrid with gzip encoding. This can significantly speed up transmission and delivery time when sending a large volume of emails.

That's it! You have successfully sent a POST request to SendGrid API by utilizing the effectiveness of a gzipped compressed payload in your requests. This feature comes in handy particularly when sending big JSON payloads while avoiding latency issues that might arise in such scenarios.

If you have any further questions regarding this document or face issues while following these instructions, don't hesitate to reach out to SendGrid support for personal assistance. Making sure you get the most out of SendGrid is our top priority, and we're always here for you!

Happy mailing!

Have more questions? Submit a request