Sending emails – SaaS Starter

Docs

Sending emails

Sending emails through Freesend.

API Endpoint

POST https://freesend.metafog.io/api/send-email

Prerequisites

Steps

Bearer Token

Ensure you put your API Key as a Bearer token in the Authorization header of the HTTP request:

'Authorization': `Bearer YOUR_API_KEY`

HTTP Body

{
    "fromName": "Your Company",  // (optional) Display name for the sender
    "fromEmail": "hello@yourdomain.com",  // Sender email address
    "to": "recipient@email.com",  // Receiver address
    "subject": "Email sent from Freesend!",  // Subject for the email
    "html": "<h1>Yay! You got the email.</h1>",  // (optional) HTML format of the email body
    "text": "Yay! You got the email.",  // (optional) Text format of the email body
    "attachments": [  // (optional) Array of attachments
        {
            "filename": "invoice.pdf",  // Name of the file
            "content": "base64EncodedContent",  // Base64 encoded file content
            "contentType": "application/pdf"  // (optional) MIME type
        }
    ]
}

API Endpoint

Send a POST Request to https://freesend.metafog.io/api/send-email

Example Usage

curl -X POST https://freesend.metafog.io/api/send-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromName": "Your Company",
    "fromEmail": "hello@yourdomain.com",
    "to": "recipient@email.com",
    "subject": "Email with attachment from Freesend!",
    "html": "<h1>Please find the invoice attached.</h1>",
    "text": "Please find the invoice attached.",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJcOkw7zDtsOmCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aC...",
        "contentType": "application/pdf"
      }
    ]
  }'

Field Reference

Main Fields

Field	Type	Required	Description
`fromName`	string	No	Display name for the sender (e.g., "Your Company")
`fromEmail`	string	Yes	Sender email address
`to`	string	Yes	Recipient email address
`subject`	string	Yes	Email subject line
`html`	string	No*	HTML content of the email
`text`	string	No*	Plain text content of the email
`attachments`	array	No	Array of attachment objects (see below)

*At least one of html or text is required.

Attachment Object Fields

Field	Type	Required	Description
`filename`	string	Yes	Name of the attachment file
`content`	string	Yes**	Base64 encoded file content
`path`	string	Yes**	File path (for server-side files only)
`contentType`	string	No	MIME type (e.g., "application/pdf", "image/png")

**Either content or path is required, but not both.

Attachment Examples

// Base64 content (recommended for API usage)
{
  "filename": "invoice.pdf",
  "content": "JVBERi0xLjQKJcOkw7zDtsOmCjUgMCBvYmoKPDwK...",
  "contentType": "application/pdf"
}
 
// Text attachment
{
  "filename": "notes.txt", 
  "content": "SGVsbG8gV29ybGQh",  // "Hello World!" in base64
  "contentType": "text/plain"
}
 
// Image attachment
{
  "filename": "logo.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "contentType": "image/png"
}
 
// Server file path (for server-side usage only)
{
  "filename": "report.xlsx",
  "path": "/path/to/report.xlsx",
  "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}

Response

Success Response (200)

{
  "message": "Email sent successfully"
}

Error Responses

400 Bad Request - Missing Authorization Header

{
  "error": "Authorization header not found."
}

400 Bad Request - Invalid Authorization Format

{
  "error": "Invalid authorization header. Create a Bearer Token."
}

400 Bad Request - Missing API Key

{
  "error": "Invalid or missing API Key."
}

400 Bad Request - Missing Required Fields

{
  "error": "Missing required field 'fromEmail'."
}

{
  "error": "Missing required field 'to'."
}

{
  "error": "Missing required field 'subject'."
}

{
  "error": "Missing required field 'text' or 'html'."
}

400 Bad Request - Inactive API Key

{
  "error": "This API key is currently inactive."
}

403 Forbidden - Invalid API Key

{
  "error": "Invalid API Key or no SMTP configuration found."
}

500 Internal Server Error - Email Sending Failed

{
  "error": "Error sending email: [specific error message]"
}

502 Bad Gateway - Transport Error

{
  "error": "Could not create the transporter object."
}

Common MIME Types

File Extension	MIME Type
`.pdf`	`application/pdf`
`.jpg`, `.jpeg`	`image/jpeg`
`.png`	`image/png`
`.gif`	`image/gif`
`.txt`	`text/plain`
`.html`	`text/html`
`.css`	`text/css`
`.js`	`application/javascript`
`.json`	`application/json`
`.xml`	`application/xml`
`.csv`	`text/csv`
`.zip`	`application/zip`
`.xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`.pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`

Best Practices

File Size Limits

Keep attachments under 25MB for best performance
For larger files, consider using cloud storage links instead

Base64 Encoding

Always encode binary files as base64
Remove any data URL prefixes (e.g., data:application/pdf;base64,)
Use proper content type headers for better email client compatibility

Multiple Attachments

{
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "base64EncodedPDF...",
      "contentType": "application/pdf"
    },
    {
      "filename": "receipt.jpg",
      "content": "base64EncodedImage...",
      "contentType": "image/jpeg"
    }
  ]
}

Setup API Keys