Email API

Simple, powerful email sending API with support for attachments and custom headers.

Quick Start

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "sender@yourdomain.com",
    "to": "recipient@example.com",
    "subject": "Hello World",
    "html": "<h1>Welcome!</h1>"
  }'

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer key_XXXXXXXXX

Basic Request Structure

Field	Type	Required	Description
from	string	Yes	Sender email address
to	string	Yes	Recipient email address(es)
subject	string	Yes	Email subject line
html	string	Yes	HTML content of the email
name	string	No	Sender name
reply_to	string	No	Reply-to email address

Recipients

Multiple Recipients

You can send to multiple recipients by separating email addresses with commas:

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "no-reply@yourdomain.com",
    "to": "user1@example.com,user2@example.com",
    "subject": "Team Update",
    "html": "<h1>Important Announcement</h1>"
  }'

Named Recipients

You can include recipient names using the format Name <email@domain.com>:

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "no-reply@yourdomain.com",
    "to": "John Doe <john@example.com>,Jane Smith <jane@example.com>",
    "subject": "Team Meeting",
    "html": "<h1>Meeting Invitation</h1>"
  }'

Reply-To Address

Set a different reply-to address using the reply_to field:

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "no-reply@yourdomain.com",
    "reply_to": "support@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Support Ticket Update",
    "html": "<h1>Your ticket has been updated</h1>"
  }'

You can also include a name in the reply-to address:

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "no-reply@yourdomain.com",
    "reply_to": "Support Team <support@yourdomain.com>",
    "to": "customer@example.com",
    "subject": "Support Ticket Update",
    "html": "<h1>Your ticket has been updated</h1>"
  }'

Attachments

Complete Example with Attachment

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "reports@yourdomain.com",
    "name": "Reports Team",
    "to": "John Smith <john@example.com>",
    "subject": "Monthly Report - January 2024",
    "html": "<h1>Monthly Report</h1><p>Please find your report attached.</p>",
    "attachments": [
      {
        "content": "VGhpcyBpcyBhbiBhdHRhY2htZW50IQo=",
        "filename": "january_report.pdf"
      },
      {
        "content": "SGVsbG8gV29ybGQh",
        "filename": "data.xlsx"
      }
    ]
  }'

Multiple Attachments with Headers

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "no-reply@yourdomain.com",
    "name": "Document System",
    "to": "Jane Doe <jane@example.com>,support@example.com",
    "reply_to": "Support <support@yourdomain.com>",
    "subject": "Your Requested Documents",
    "html": "<h1>Documents Ready</h1><p>Please find your requested documents attached.</p>",
    "attachments": [
      {
        "content": "VGhpcyBpcyBhbiBhdHRhY2htZW50IQo=",
        "filename": "document1.pdf"
      },
      {
        "content": "SGVsbG8gV29ybGQh",
        "filename": "document2.pdf"
      }
    ],
    "headers": {
      "X-Priority": "1",
      "X-Document-Type": "confidential",
      "List-Unsubscribe": "<https://yourdomain.com/unsubscribe>",
      "X-Tracking-ID": "doc-123456"
    }
  }'

Custom Headers

Complete Example with Headers

curl -X POST 'https://api.shoutbox.email/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "newsletter@yourdomain.com",
    "name": "Newsletter Team",
    "to": "Subscriber <subscriber@example.com>",
    "reply_to": "Newsletter Support <newsletter-support@yourdomain.com>",
    "subject": "Your Weekly Newsletter",
    "html": "<h1>This Week'\''s Updates</h1><p>Latest news and updates...</p>",
    "headers": {
      "List-Unsubscribe": "<https://yourdomain.com/unsubscribe>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
      "X-Campaign-ID": "newsletter_2024_01",
      "X-Mailer": "ShoutboxAPI/1.0",
      "Precedence": "bulk",
      "X-Auto-Response-Suppress": "OOF, AutoReply"
    }
  }'

Security Best Practices

Follow these security guidelines to ensure safe API usage:

1. Never share your API key publicly
2. Use environment variables to store your API key
3. Implement proper error handling
4. Validate email addresses before sending
5. Use HTTPS for all API calls
6. Base64 encode attachments properly
7. Keep attachment sizes reasonable

Rate Limits

Please contact support for information about rate limits for your API key.

Support

For additional support or questions, please contact our support team.