Skip to main content
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 <[email protected]>",
  "to": "[email protected]",
  "subject": "Welcome to Our Service!",
  "html": "<p>Hello {{name}}!</p>",
  "template_id": "welcome-template",
  "text": "Hello {{name}}!",
  "cc": "[email protected]",
  "bcc": "[email protected]",
  "reply_to": "[email protected]",
  "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>"
    }
  ]
}
'
{
  "id": "0195c9e3-5067-741d-be87-a4f75ef93372"
}

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:

Maximum string length: 100
Example:

"Your Name <[email protected]>"

​
to
required

Recipient email addresses. Maximum 50 recipients allowed.

Example:

"[email protected]"

​
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

CC recipient addresses. Maximum 50 recipients allowed.

Example:

"[email protected]"

​
bcc

BCC recipient addresses. Maximum 50 recipients allowed.

Example:

"[email protected]"

​
reply_to

Reply-to addresses. Maximum 50 recipients allowed.

Example:

"[email protected]"

​
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

Response

Email successfully queued for sending

​
id
string

Unique identifier for the sent email

Example:

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