Sending Emails | docs.do.dev

The Send.dev Email API allows you to send transactional and marketing emails with high deliverability. This page covers all aspects of sending emails.

Send an Email

POST/v1/emailsRequires API Key

Send a single email

Basic Request

curl -X POST https://api.send.dev/v1/emails \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@mail.yourdomain.com",
    "to": "user@example.com",
    "subject": "Welcome to our platform",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    "text": "Welcome! Thanks for signing up."
  }'

200Email queued successfully

{
"id": "email_01HXYZ123456789",
"status": "queued",
"from": "hello@mail.yourdomain.com",
"to": "user@example.com",
"subject": "Welcome to our platform",
"created_at": "2025-01-13T10:30:00Z"
}

Request Parameters

Body Parameters

Name	Type	Required	Description
from	string	required	Sender email address. Must be from a verified domain.
to	string \| string[]	required	Recipient email address(es). Max 50 recipients.
subject	string	required	Email subject line. Max 998 characters.
html	string	optional	HTML content of the email. Either html or text is required.
text	string	optional	Plain text content of the email. Either html or text is required.
cc	string \| string[]	optional	CC recipients. Max 50 addresses.
bcc	string \| string[]	optional	BCC recipients. Max 50 addresses.
reply_to	string	optional	Reply-to address for recipient responses.
attachments	Attachment[]	optional	File attachments. See Attachments section.
headers	object	optional	Custom email headers.
tags	string[]	optional	Tags for categorizing and filtering emails.
metadata	object	optional	Custom metadata stored with the email.
track_opens	boolean	optional	Enable open tracking. Default: true(default: true)
track_clicks	boolean	optional	Enable click tracking. Default: true(default: true)

Advanced Examples

Multiple Recipients

Send to multiple recipients in one API call:

curl -X POST https://api.send.dev/v1/emails \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "team@mail.yourdomain.com",
    "to": ["alice@example.com", "bob@example.com"],
    "cc": ["manager@example.com"],
    "bcc": ["archive@yourdomain.com"],
    "subject": "Project Update",
    "html": "<p>Here is the latest project update...</p>"
  }'

Recipient Limits

Each email can have up to 50 recipients across to, cc, and bcc combined. For larger sends, use batch sending.

Personalized Sender Name

Include a display name with the sender address:

{
  "from": "Alex from Acme <alex@mail.acme.com>",
  "to": "customer@example.com",
  "subject": "Your order has shipped"
}

Reply-To Address

Set a different reply-to address:

{
  "from": "noreply@mail.yourdomain.com",
  "reply_to": "support@yourdomain.com",
  "to": "customer@example.com",
  "subject": "Your receipt"
}

Custom Headers

Add custom email headers for tracking or routing:

{
  "from": "notifications@mail.yourdomain.com",
  "to": "user@example.com",
  "subject": "Account Alert",
  "html": "<p>Your password was changed.</p>",
  "headers": {
    "X-Entity-Ref-ID": "user_12345",
    "X-Priority": "1",
    "List-Unsubscribe": "<mailto:unsubscribe@yourdomain.com>"
  }
}

Tags and Metadata

Add tags for filtering and metadata for your records:

{
  "from": "billing@mail.yourdomain.com",
  "to": "customer@example.com",
  "subject": "Invoice #12345",
  "html": "<p>Your invoice is attached.</p>",
  "tags": ["billing", "invoice", "q1-2025"],
  "metadata": {
    "invoice_id": "inv_12345",
    "customer_id": "cust_67890",
    "amount": "99.99"
  }
}

Batch Sending

POST/v1/emails/batchRequires API Key

Send multiple emails in a single request

For high-volume sending, use the batch endpoint:

curl -X POST https://api.send.dev/v1/emails/batch \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "from": "newsletter@mail.yourdomain.com",
        "to": "alice@example.com",
        "subject": "Weekly Digest",
        "html": "<p>Hello Alice, here is your digest...</p>"
      },
      {
        "from": "newsletter@mail.yourdomain.com",
        "to": "bob@example.com",
        "subject": "Weekly Digest",
        "html": "<p>Hello Bob, here is your digest...</p>"
      }
    ]
  }'

200Batch queued

{
"batch_id": "batch_01HXYZ123456789",
"total": 2,
"queued": 2,
"failed": 0,
"emails": [
  { "id": "email_01HXYZ111111111", "status": "queued", "to": "alice@example.com" },
  { "id": "email_01HXYZ222222222", "status": "queued", "to": "bob@example.com" }
]
}

Batch Limits

Each batch request can contain up to 100 emails. For larger volumes, make multiple batch requests.

Retrieve Email Status

GET/v1/emails/:idRequires API Key

Get details and status of a sent email

curl https://api.send.dev/v1/emails/email_01HXYZ123456789 \
  -H "Authorization: Bearer sk_live_your_api_key"

200Email details

{
"id": "email_01HXYZ123456789",
"status": "delivered",
"from": "hello@mail.yourdomain.com",
"to": "user@example.com",
"subject": "Welcome to our platform",
"created_at": "2025-01-13T10:30:00Z",
"sent_at": "2025-01-13T10:30:01Z",
"delivered_at": "2025-01-13T10:30:03Z",
"opened_at": "2025-01-13T10:35:00Z",
"opened_count": 2,
"clicked_at": "2025-01-13T10:36:00Z",
"clicked_count": 1,
"clicks": [
  { "url": "https://yourdomain.com/welcome", "count": 1, "first_at": "2025-01-13T10:36:00Z" }
],
"tags": ["welcome"],
"metadata": { "user_id": "user_12345" }
}

Email Statuses

Status	Description
`queued`	Email accepted and waiting to be sent
`sending`	Email is being sent to the mail server
`sent`	Email handed off to the receiving server
`delivered`	Email confirmed delivered to inbox
`bounced`	Email bounced (hard or soft bounce)
`complained`	Recipient marked as spam
`failed`	Email failed to send (see error)

List Emails

GET/v1/emailsRequires API Key

List sent emails with filtering

curl "https://api.send.dev/v1/emails?status=delivered&limit=20" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Name	Type	Required	Description
status	string	optional	Filter by status: queued, sent, delivered, bounced, complained, failed
to	string	optional	Filter by recipient email address
from	string	optional	Filter by sender email address
tag	string	optional	Filter by tag
created_after	string	optional	Filter emails created after this ISO timestamp
created_before	string	optional	Filter emails created before this ISO timestamp
limit	integer	optional	Number of results (1-100)(default: 20)
cursor	string	optional	Pagination cursor from previous response

Error Handling

Validation Errors

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": [
      { "field": "to", "message": "Invalid email address format" },
      { "field": "subject", "message": "Subject is required" }
    ]
  }
}

Domain Not Verified

{
  "error": {
    "code": "domain_not_verified",
    "message": "Domain 'mail.example.com' is not verified",
    "docs_url": "https://send.dev/docs/email/domains"
  }
}

Rate Limited

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}

Best Practices

Always include plain text - Some email clients only display plain text
Use a consistent sender - Maintain sender reputation
Include unsubscribe links - Required for marketing emails (CAN-SPAM)
Handle bounces - Remove bounced addresses from your lists
Use tags - Make it easy to filter and analyze emails
Store metadata - Link emails to your internal records
Monitor deliverability - Check your dashboard regularly

SDK Examples

Send emails and check status using your preferred language:

# Send an email
curl -X POST https://api.send.dev/v1/emails \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "from": "hello@mail.yourdomain.com",
  "to": "user@example.com",
  "subject": "Welcome!",
  "html": "<h1>Welcome to our platform!</h1>",
  "text": "Welcome to our platform!",
  "tags": ["welcome", "onboarding"],
  "metadata": {"user_id": "user_123"}
}'

# Check email status
curl https://api.send.dev/v1/emails/email_01HXYZ123456789 \
-H "Authorization: Bearer sk_live_your_api_key"

Body Parameters

Query Parameters

On this page