Send Email with cURL
Learn how to send emails using the Transactional REST API with cURL. Perfect for testing, scripting, and understanding the API.
Beginner
5 minutesemail
getting-started
api
rest
curl
Prerequisites
- cURL installed (comes with most operating systems)
- Transactional account with API key
- Verified sending domain
CODE
Full Example
#!/bin/bash
# Send a simple email using the Transactional API
curl -X POST https://api.transactional.dev/v1/emails \
-H "Authorization: Bearer $TRANSACTIONAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "hello@yourdomain.com",
"to": "recipient@example.com",
"subject": "Hello from Transactional!",
"html": "<h1>Welcome!</h1><p>This is your first email.</p>",
"text": "Welcome! This is your first email."
}'
Understanding the API
Base URL
All API requests go to:
https://api.transactional.dev/v1
Authentication
Include your API key in the Authorization header:
-H "Authorization: Bearer YOUR_API_KEY"Request Format
Send JSON data with the appropriate content type:
-H "Content-Type: application/json"API Reference
Send Email Endpoint
POST /v1/emails
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Sender email address |
to | string | string[] | Yes | Recipient email(s) |
subject | string | Yes* | Email subject (*not required if using template) |
html | string | No | HTML content |
text | string | No | Plain text content |
cc | string | string[] | No | CC recipients |
bcc | string | string[] | No | BCC recipients |
replyTo | string | No | Reply-to address |
templateId | string | No | Template ID to use |
templateData | object | No | Data for template variables |
attachments | array | No | File attachments |
metadata | object | No | Custom metadata |
tags | string[] | No | Tags for categorization |
Success Response
{
"data": {
"id": "msg_abc123xyz",
"status": "queued",
"from": "hello@yourdomain.com",
"to": ["recipient@example.com"],
"subject": "Hello from Transactional!",
"createdAt": "2024-01-15T10:30:00Z"
}
}Error Response
{
"error": {
"code": "INVALID_EMAIL",
"message": "The email address 'invalid' is not valid.",
"details": {
"field": "to"
}
}
}Common cURL Options
| Option | Description |
|---|---|
-X POST | HTTP method |
-H | Add header |
-d | Request body |
-s | Silent mode (no progress bar) |
-w '\n' | Add newline after response |
-o response.json | Save response to file |
-i | Include response headers |
Checking Email Status
After sending, you can check the email status:
curl -X GET https://api.transactional.dev/v1/emails/msg_abc123xyz \
-H "Authorization: Bearer $TRANSACTIONAL_API_KEY"Response:
{
"data": {
"id": "msg_abc123xyz",
"status": "delivered",
"from": "hello@yourdomain.com",
"to": ["recipient@example.com"],
"subject": "Hello from Transactional!",
"createdAt": "2024-01-15T10:30:00Z",
"deliveredAt": "2024-01-15T10:30:02Z",
"opens": 1,
"clicks": 0
}
}Scripting Tips
Store API Key Securely
# Set in your shell profile (.bashrc, .zshrc)
export TRANSACTIONAL_API_KEY="your_api_key_here"Parse Response with jq
# Extract email ID
curl -s -X POST https://api.transactional.dev/v1/emails \
-H "Authorization: Bearer $TRANSACTIONAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"hello@yourdomain.com","to":"test@example.com","subject":"Test","text":"Hello"}' \
| jq -r '.data.id'Error Handling in Scripts
#!/bin/bash
response=$(curl -s -w "\n%{http_code}" -X POST https://api.transactional.dev/v1/emails \
-H "Authorization: Bearer $TRANSACTIONAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"hello@yourdomain.com","to":"test@example.com","subject":"Test","text":"Hello"}')
# Split response body and status code
body=$(echo "$response" | sed '$d')
status_code=$(echo "$response" | tail -n1)
if [ "$status_code" -eq 200 ]; then
echo "Email sent successfully!"
echo "$body" | jq '.data.id'
else
echo "Failed to send email (HTTP $status_code)"
echo "$body" | jq '.error'
exit 1
fi