cURL Examples for Common Use Cases

These cURL examples cover common SendGrid email use cases, including sending a single message, sending to multiple recipients, using a template, and scheduling a send.

Hello, World

Send a "Hello, World!" email through SendGrid's v3 Mail Send endpoint. Replace YOUR_API_KEY with your actual API key:

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/send \
3  --header 'Authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"personalizations": [{"to": [{"email": "recipient@example.com"}]}],"from": {"email": "sendeexampexample@example.com"},"subject": "Hello, World!","content": [{"type": "text/plain", "value": "Heya!"}]}'

Sending a Basic Email to Multiple Recipients

Send an email to multiple addresses by adding cc entries to the personalization:

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/send \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"personalizations": [{"to": [{"email": "recipient@example.com"}],"cc": [{"email":"recipient2@example.com"}, {"email": "recipient3@example.com"}, {"email":"recipient4@example.com"}]}], "from": {"email": "sendeexampexample@example.com"},"subject":"Hello, World!", "content": [{"type": "text/plain", "value": "Heya!"}]}'

Sending a Basic Email Using a Template

Send an email using a template by including the template_id field. Replace YOUR_TEMPLATE_ID with your actual template ID:

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/send \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"personalizations": [{"to": [{"email": "recipient@example.com"}]}],"from": {"email": "sendeexampexample@example.com"},"subject":"Hello, World!","content": [{"type": "text/plain","value": "Heya!"}], "template_id" : "YOUR_TEMPLATE_ID"}'

Sending a Basic Email with Attachment

Send an email with attachments by including an attachments array containing Base64-encoded file content:

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/send \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"personalizations": [{"to": [{"email": "recipient@example.com"}]}],"from": {"email": "sender@example.com"},"subject":"Hello, World!","content": [{"type": "text/html","value": "Hey, Please find attachment."}], "attachments": [{"content": "BASE64_ENCODED_CONTENT", "type": "text/plain", "filename": "attachment.txt"}]}'

Sending a Basic Email at a Scheduled Time

Send an email at a specified time by including the send_at field. Replace UNIX_TIMESTAMP_HERE with your desired timestamp:

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/send \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"personalizations": [{"to": [{"email": "recipient@example.com"}]}],"from": {"email": "sendeexampexample@example.com"},"subject":"Hello, World!","content": [{"type": "text/plain","value": "Heya!"}], "send_at" : UNIX_TIMESTAMP_HERE}'

Scheduling and Cancelling an Email

You can schedule an email to be sent up to 72 hours in the future by using the send_at parameter, then cancel that same scheduled email by using the Cancel Scheduled Sends endpoint. To schedule and cancel an email, follow these steps:

Step 1: Generate a batch ID

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/batch \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \

Step 2: Schedule the email to be sent, using your new batch ID

1curl --request POST \
2  --url https://api.sendgrid.com/v3/mail/send \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"personalizations": [{"to": [{"email": "recipient@example.com"}]}],"from": {"email": "sendeexampexample@example.com"},"subject":"Hello, World!","content": [{"type": "text/plain","value": "Heya!"}], "send_at" : UNIX_TIMESTAMP_HERE, "batch_id" : "YOUR_BATCH_ID"}'

Step 3: Cancel the scheduled email

1curl --request POST \
2  --url https://api.sendgrid.com/v3/user/scheduled_sends \
3  --header 'authorization: Bearer YOUR_API_KEY' \
4  --header 'Content-Type: application/json' \
5  --data '{"batch_id":"YOUR_BATCH_ID","status":"cancel"}'