Send email

curl --request POST \
  --url https://api.maildiver.com/v1/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "Your Name <sender@yourdomain.com>",
  "to": "recipient@example.com",
  "subject": "Welcome to Our Service!",
  "html": "<p>Hello {{name}}!</p>",
  "template_id": "welcome-template",
  "text": "Hello {{name}}!",
  "cc": "cc@example.com",
  "bcc": "bcc@example.com",
  "reply_to": "reply@yourdomain.com",
  "variables": {
    "date": "27 November",
    "plan": {
      "value": "Pro Plan",
      "default": "Free Plan"
    },
    "company": {
      "value": null,
      "default": "our company"
    },
    "title": {
      "value": null,
      "default": "valued customer"
    }
  },
  "attachments": [
    {
      "filename": "<string>",
      "path": "<string>",
      "content": "aSDinaTvuI8gbWludGxpZnk=",
      "content_type": "<string>"
    }
  ]
}
'

import requests

url = "https://api.maildiver.com/v1/emails"

payload = {
    "from": "Your Name <sender@yourdomain.com>",
    "to": "recipient@example.com",
    "subject": "Welcome to Our Service!",
    "html": "<p>Hello {{name}}!</p>",
    "template_id": "welcome-template",
    "text": "Hello {{name}}!",
    "cc": "cc@example.com",
    "bcc": "bcc@example.com",
    "reply_to": "reply@yourdomain.com",
    "variables": {
        "date": "27 November",
        "plan": {
            "value": "Pro Plan",
            "default": "Free Plan"
        },
        "company": {
            "value": None,
            "default": "our company"
        },
        "title": {
            "value": None,
            "default": "valued customer"
        }
    },
    "attachments": [
        {
            "filename": "<string>",
            "path": "<string>",
            "content": "aSDinaTvuI8gbWludGxpZnk=",
            "content_type": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: 'Your Name <sender@yourdomain.com>',
    to: 'recipient@example.com',
    subject: 'Welcome to Our Service!',
    html: '<p>Hello {{name}}!</p>',
    template_id: 'welcome-template',
    text: 'Hello {{name}}!',
    cc: 'cc@example.com',
    bcc: 'bcc@example.com',
    reply_to: 'reply@yourdomain.com',
    variables: {
      date: '27 November',
      plan: {value: 'Pro Plan', default: 'Free Plan'},
      company: {value: null, default: 'our company'},
      title: {value: null, default: 'valued customer'}
    },
    attachments: [
      {
        filename: '<string>',
        path: '<string>',
        content: 'aSDinaTvuI8gbWludGxpZnk=',
        content_type: '<string>'
      }
    ]
  })
};

fetch('https://api.maildiver.com/v1/emails', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maildiver.com/v1/emails",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => 'Your Name <sender@yourdomain.com>',
    'to' => 'recipient@example.com',
    'subject' => 'Welcome to Our Service!',
    'html' => '<p>Hello {{name}}!</p>',
    'template_id' => 'welcome-template',
    'text' => 'Hello {{name}}!',
    'cc' => 'cc@example.com',
    'bcc' => 'bcc@example.com',
    'reply_to' => 'reply@yourdomain.com',
    'variables' => [
        'date' => '27 November',
        'plan' => [
                'value' => 'Pro Plan',
                'default' => 'Free Plan'
        ],
        'company' => [
                'value' => null,
                'default' => 'our company'
        ],
        'title' => [
                'value' => null,
                'default' => 'valued customer'
        ]
    ],
    'attachments' => [
        [
                'filename' => '<string>',
                'path' => '<string>',
                'content' => 'aSDinaTvuI8gbWludGxpZnk=',
                'content_type' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maildiver.com/v1/emails"

	payload := strings.NewReader("{\n  \"from\": \"Your Name <sender@yourdomain.com>\",\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Welcome to Our Service!\",\n  \"html\": \"<p>Hello {{name}}!</p>\",\n  \"template_id\": \"welcome-template\",\n  \"text\": \"Hello {{name}}!\",\n  \"cc\": \"cc@example.com\",\n  \"bcc\": \"bcc@example.com\",\n  \"reply_to\": \"reply@yourdomain.com\",\n  \"variables\": {\n    \"date\": \"27 November\",\n    \"plan\": {\n      \"value\": \"Pro Plan\",\n      \"default\": \"Free Plan\"\n    },\n    \"company\": {\n      \"value\": null,\n      \"default\": \"our company\"\n    },\n    \"title\": {\n      \"value\": null,\n      \"default\": \"valued customer\"\n    }\n  },\n  \"attachments\": [\n    {\n      \"filename\": \"<string>\",\n      \"path\": \"<string>\",\n      \"content\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"content_type\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.maildiver.com/v1/emails")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"Your Name <sender@yourdomain.com>\",\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Welcome to Our Service!\",\n  \"html\": \"<p>Hello {{name}}!</p>\",\n  \"template_id\": \"welcome-template\",\n  \"text\": \"Hello {{name}}!\",\n  \"cc\": \"cc@example.com\",\n  \"bcc\": \"bcc@example.com\",\n  \"reply_to\": \"reply@yourdomain.com\",\n  \"variables\": {\n    \"date\": \"27 November\",\n    \"plan\": {\n      \"value\": \"Pro Plan\",\n      \"default\": \"Free Plan\"\n    },\n    \"company\": {\n      \"value\": null,\n      \"default\": \"our company\"\n    },\n    \"title\": {\n      \"value\": null,\n      \"default\": \"valued customer\"\n    }\n  },\n  \"attachments\": [\n    {\n      \"filename\": \"<string>\",\n      \"path\": \"<string>\",\n      \"content\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"content_type\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maildiver.com/v1/emails")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"Your Name <sender@yourdomain.com>\",\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Welcome to Our Service!\",\n  \"html\": \"<p>Hello {{name}}!</p>\",\n  \"template_id\": \"welcome-template\",\n  \"text\": \"Hello {{name}}!\",\n  \"cc\": \"cc@example.com\",\n  \"bcc\": \"bcc@example.com\",\n  \"reply_to\": \"reply@yourdomain.com\",\n  \"variables\": {\n    \"date\": \"27 November\",\n    \"plan\": {\n      \"value\": \"Pro Plan\",\n      \"default\": \"Free Plan\"\n    },\n    \"company\": {\n      \"value\": null,\n      \"default\": \"our company\"\n    },\n    \"title\": {\n      \"value\": null,\n      \"default\": \"valued customer\"\n    }\n  },\n  \"attachments\": [\n    {\n      \"filename\": \"<string>\",\n      \"path\": \"<string>\",\n      \"content\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"content_type\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "0195c9e3-5067-741d-be87-a4f75ef93372"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Send email

curl --request POST \
  --url https://api.maildiver.com/v1/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "Your Name <sender@yourdomain.com>",
  "to": "recipient@example.com",
  "subject": "Welcome to Our Service!",
  "html": "<p>Hello {{name}}!</p>",
  "template_id": "welcome-template",
  "text": "Hello {{name}}!",
  "cc": "cc@example.com",
  "bcc": "bcc@example.com",
  "reply_to": "reply@yourdomain.com",
  "variables": {
    "date": "27 November",
    "plan": {
      "value": "Pro Plan",
      "default": "Free Plan"
    },
    "company": {
      "value": null,
      "default": "our company"
    },
    "title": {
      "value": null,
      "default": "valued customer"
    }
  },
  "attachments": [
    {
      "filename": "<string>",
      "path": "<string>",
      "content": "aSDinaTvuI8gbWludGxpZnk=",
      "content_type": "<string>"
    }
  ]
}
'

import requests

url = "https://api.maildiver.com/v1/emails"

payload = {
    "from": "Your Name <sender@yourdomain.com>",
    "to": "recipient@example.com",
    "subject": "Welcome to Our Service!",
    "html": "<p>Hello {{name}}!</p>",
    "template_id": "welcome-template",
    "text": "Hello {{name}}!",
    "cc": "cc@example.com",
    "bcc": "bcc@example.com",
    "reply_to": "reply@yourdomain.com",
    "variables": {
        "date": "27 November",
        "plan": {
            "value": "Pro Plan",
            "default": "Free Plan"
        },
        "company": {
            "value": None,
            "default": "our company"
        },
        "title": {
            "value": None,
            "default": "valued customer"
        }
    },
    "attachments": [
        {
            "filename": "<string>",
            "path": "<string>",
            "content": "aSDinaTvuI8gbWludGxpZnk=",
            "content_type": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: 'Your Name <sender@yourdomain.com>',
    to: 'recipient@example.com',
    subject: 'Welcome to Our Service!',
    html: '<p>Hello {{name}}!</p>',
    template_id: 'welcome-template',
    text: 'Hello {{name}}!',
    cc: 'cc@example.com',
    bcc: 'bcc@example.com',
    reply_to: 'reply@yourdomain.com',
    variables: {
      date: '27 November',
      plan: {value: 'Pro Plan', default: 'Free Plan'},
      company: {value: null, default: 'our company'},
      title: {value: null, default: 'valued customer'}
    },
    attachments: [
      {
        filename: '<string>',
        path: '<string>',
        content: 'aSDinaTvuI8gbWludGxpZnk=',
        content_type: '<string>'
      }
    ]
  })
};

fetch('https://api.maildiver.com/v1/emails', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maildiver.com/v1/emails",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => 'Your Name <sender@yourdomain.com>',
    'to' => 'recipient@example.com',
    'subject' => 'Welcome to Our Service!',
    'html' => '<p>Hello {{name}}!</p>',
    'template_id' => 'welcome-template',
    'text' => 'Hello {{name}}!',
    'cc' => 'cc@example.com',
    'bcc' => 'bcc@example.com',
    'reply_to' => 'reply@yourdomain.com',
    'variables' => [
        'date' => '27 November',
        'plan' => [
                'value' => 'Pro Plan',
                'default' => 'Free Plan'
        ],
        'company' => [
                'value' => null,
                'default' => 'our company'
        ],
        'title' => [
                'value' => null,
                'default' => 'valued customer'
        ]
    ],
    'attachments' => [
        [
                'filename' => '<string>',
                'path' => '<string>',
                'content' => 'aSDinaTvuI8gbWludGxpZnk=',
                'content_type' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maildiver.com/v1/emails"

	payload := strings.NewReader("{\n  \"from\": \"Your Name <sender@yourdomain.com>\",\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Welcome to Our Service!\",\n  \"html\": \"<p>Hello {{name}}!</p>\",\n  \"template_id\": \"welcome-template\",\n  \"text\": \"Hello {{name}}!\",\n  \"cc\": \"cc@example.com\",\n  \"bcc\": \"bcc@example.com\",\n  \"reply_to\": \"reply@yourdomain.com\",\n  \"variables\": {\n    \"date\": \"27 November\",\n    \"plan\": {\n      \"value\": \"Pro Plan\",\n      \"default\": \"Free Plan\"\n    },\n    \"company\": {\n      \"value\": null,\n      \"default\": \"our company\"\n    },\n    \"title\": {\n      \"value\": null,\n      \"default\": \"valued customer\"\n    }\n  },\n  \"attachments\": [\n    {\n      \"filename\": \"<string>\",\n      \"path\": \"<string>\",\n      \"content\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"content_type\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.maildiver.com/v1/emails")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"Your Name <sender@yourdomain.com>\",\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Welcome to Our Service!\",\n  \"html\": \"<p>Hello {{name}}!</p>\",\n  \"template_id\": \"welcome-template\",\n  \"text\": \"Hello {{name}}!\",\n  \"cc\": \"cc@example.com\",\n  \"bcc\": \"bcc@example.com\",\n  \"reply_to\": \"reply@yourdomain.com\",\n  \"variables\": {\n    \"date\": \"27 November\",\n    \"plan\": {\n      \"value\": \"Pro Plan\",\n      \"default\": \"Free Plan\"\n    },\n    \"company\": {\n      \"value\": null,\n      \"default\": \"our company\"\n    },\n    \"title\": {\n      \"value\": null,\n      \"default\": \"valued customer\"\n    }\n  },\n  \"attachments\": [\n    {\n      \"filename\": \"<string>\",\n      \"path\": \"<string>\",\n      \"content\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"content_type\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maildiver.com/v1/emails")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"Your Name <sender@yourdomain.com>\",\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Welcome to Our Service!\",\n  \"html\": \"<p>Hello {{name}}!</p>\",\n  \"template_id\": \"welcome-template\",\n  \"text\": \"Hello {{name}}!\",\n  \"cc\": \"cc@example.com\",\n  \"bcc\": \"bcc@example.com\",\n  \"reply_to\": \"reply@yourdomain.com\",\n  \"variables\": {\n    \"date\": \"27 November\",\n    \"plan\": {\n      \"value\": \"Pro Plan\",\n      \"default\": \"Free Plan\"\n    },\n    \"company\": {\n      \"value\": null,\n      \"default\": \"our company\"\n    },\n    \"title\": {\n      \"value\": null,\n      \"default\": \"valued customer\"\n    }\n  },\n  \"attachments\": [\n    {\n      \"filename\": \"<string>\",\n      \"path\": \"<string>\",\n      \"content\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"content_type\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "0195c9e3-5067-741d-be87-a4f75ef93372"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

API key with format "Bearer {your-api-key}"

Body

application/json

from

string

required

Sender email address. Must be in one of these formats:

"Name" <email@domain.com>
Name <email@domain.com>
email@domain.com

Maximum string length: 100

Example:

"Your Name <sender@yourdomain.com>"

required

Recipient email addresses. Maximum 50 recipients allowed.

Example:

"recipient@example.com"

subject

string

required

Email subject line

Maximum string length: 100

Example:

"Welcome to Our Service!"

html

string

HTML content of the email. Required if template_id is not provided.

Maximum size: 40MB
Cannot be used together with template_id

Example:

"<p>Hello {{name}}!</p>"

template_id

string

ID of the email template. Required if html is not provided.

Cannot be used together with html
Must reference an existing template
Template must have valid HTML content

Example:

"welcome-template"

text

string

Plain text version of the email. Maximum size 10MB.

Example:

"Hello {{name}}!"

CC recipient addresses. Maximum 50 recipients allowed.

Example:

"cc@example.com"

bcc

BCC recipient addresses. Maximum 50 recipients allowed.

Example:

"bcc@example.com"

reply_to

Reply-to addresses. Maximum 50 recipients allowed.

Example:

"reply@yourdomain.com"

variables

object

Template variables for personalization. Maximum 100 properties allowed. Variables are referenced in templates using double curly braces: {{variable_name}}

Note: When using templates with variables (e.g., {{variable_name}}):

Default values can be defined in the template
Values provided through this API field will override any template defaults
Default values will be used when:
- The variable is not provided at all
- The variable is explicitly set to null
- When using object format and value is null or undefined

Each variable can be:

A string
A number
An object with:
- value: string, number, or null
- default: string or number (used when value is null)

Example:

{
  "date": "27 November",
  "plan": {
    "value": "Pro Plan",
    "default": "Free Plan"
  },
  "company": { "value": null, "default": "our company" },
  "title": {
    "value": null,
    "default": "valued customer"
  }
}

attachments

object[]

File attachments. You can attach files using either base64 encoded content or a URL path.

Limits:

Maximum 10 attachments allowed
Total size must not exceed 40MB for all attachments combined
Each attachment must have:
- filename (required)
- Either path OR content (one must be provided)
- content_type (optional, but highly recommended)
  - If not provided, falls back to application/octet-stream

Tip: You can upload files through the "Assets" in the template page. These files will be served through our CDN, ensuring they are cached and optimized for delivery.

Example using base64 content:

{
  "attachments": [{
    "filename": "document.pdf",
    "content": "base64EncodedString==",
    "content_type": "application/pdf"
  }]
}

Example using URL path:

{
  "attachments": [{
    "filename": "document.pdf",
    "path": "https://example.com/files/document.pdf",
    "content_type": "application/pdf"
  }]
}

Example with multiple attachments:

{
  "attachments": [
    {
      "filename": "document.pdf",
      "content": "base64EncodedString==",
      "content_type": "application/pdf"
    },
    {
      "filename": "image.jpg",
      "path": "https://example.com/files/image.jpg",
      "content_type": "image/jpeg"
    }
  ]
}

Common errors:

"Too many attachments: 11. Max is 10"
"Total attachments size exceeds maximum of 40MB"
"attachments[0].filename is required"
"attachments[0] must have either path or content"
"attachments[0].path must be a valid URL"
"attachments[0].content must be a valid base64 encoded string"

Maximum array length: 10

Show child attributes

Response

Email successfully queued for sending

string

Unique identifier for the sent email

Example:

"0195c9e3-5067-741d-be87-a4f75ef93372"

Managed (Cloud)

Knowledge

Self-Hosted

API Reference

Send email

Authorizations

Body

Response