Send Email

curl --request POST \
  --url https://api.example.com/emails \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "<string>",
  "to": [
    "<string>"
  ],
  "subject": "<string>",
  "html": "<string>",
  "text": "<string>",
  "cc": [
    "<string>"
  ],
  "bcc": [
    "<string>"
  ],
  "reply_to": [
    "<string>"
  ],
  "headers": {},
  "attachments": [
    {}
  ],
  "idempotencyKey": "<string>",
  "tracking": {}
}
'

import requests

url = "https://api.example.com/emails"

payload = {
    "from": "<string>",
    "to": ["<string>"],
    "subject": "<string>",
    "html": "<string>",
    "text": "<string>",
    "cc": ["<string>"],
    "bcc": ["<string>"],
    "reply_to": ["<string>"],
    "headers": {},
    "attachments": [{}],
    "idempotencyKey": "<string>",
    "tracking": {}
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: '<string>',
    to: ['<string>'],
    subject: '<string>',
    html: '<string>',
    text: '<string>',
    cc: ['<string>'],
    bcc: ['<string>'],
    reply_to: ['<string>'],
    headers: {},
    attachments: [{}],
    idempotencyKey: '<string>',
    tracking: {}
  })
};

fetch('https://api.example.com/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.example.com/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' => '<string>',
    'to' => [
        '<string>'
    ],
    'subject' => '<string>',
    'html' => '<string>',
    'text' => '<string>',
    'cc' => [
        '<string>'
    ],
    'bcc' => [
        '<string>'
    ],
    'reply_to' => [
        '<string>'
    ],
    'headers' => [
        
    ],
    'attachments' => [
        [
                
        ]
    ],
    'idempotencyKey' => '<string>',
    'tracking' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "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.example.com/emails"

	payload := strings.NewReader("{\n  \"from\": \"<string>\",\n  \"to\": [\n    \"<string>\"\n  ],\n  \"subject\": \"<string>\",\n  \"html\": \"<string>\",\n  \"text\": \"<string>\",\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"reply_to\": [\n    \"<string>\"\n  ],\n  \"headers\": {},\n  \"attachments\": [\n    {}\n  ],\n  \"idempotencyKey\": \"<string>\",\n  \"tracking\": {}\n}")

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

	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.example.com/emails")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"<string>\",\n  \"to\": [\n    \"<string>\"\n  ],\n  \"subject\": \"<string>\",\n  \"html\": \"<string>\",\n  \"text\": \"<string>\",\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"reply_to\": [\n    \"<string>\"\n  ],\n  \"headers\": {},\n  \"attachments\": [\n    {}\n  ],\n  \"idempotencyKey\": \"<string>\",\n  \"tracking\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"<string>\",\n  \"to\": [\n    \"<string>\"\n  ],\n  \"subject\": \"<string>\",\n  \"html\": \"<string>\",\n  \"text\": \"<string>\",\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"reply_to\": [\n    \"<string>\"\n  ],\n  \"headers\": {},\n  \"attachments\": [\n    {}\n  ],\n  \"idempotencyKey\": \"<string>\",\n  \"tracking\": {}\n}"

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

{
  "id": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "to": "<string>",
  "subject": "<string>",
  "from": "<string>"
}

Send Email

curl --request POST \
  --url https://api.example.com/emails \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "<string>",
  "to": [
    "<string>"
  ],
  "subject": "<string>",
  "html": "<string>",
  "text": "<string>",
  "cc": [
    "<string>"
  ],
  "bcc": [
    "<string>"
  ],
  "reply_to": [
    "<string>"
  ],
  "headers": {},
  "attachments": [
    {}
  ],
  "idempotencyKey": "<string>",
  "tracking": {}
}
'

import requests

url = "https://api.example.com/emails"

payload = {
    "from": "<string>",
    "to": ["<string>"],
    "subject": "<string>",
    "html": "<string>",
    "text": "<string>",
    "cc": ["<string>"],
    "bcc": ["<string>"],
    "reply_to": ["<string>"],
    "headers": {},
    "attachments": [{}],
    "idempotencyKey": "<string>",
    "tracking": {}
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: '<string>',
    to: ['<string>'],
    subject: '<string>',
    html: '<string>',
    text: '<string>',
    cc: ['<string>'],
    bcc: ['<string>'],
    reply_to: ['<string>'],
    headers: {},
    attachments: [{}],
    idempotencyKey: '<string>',
    tracking: {}
  })
};

fetch('https://api.example.com/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.example.com/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' => '<string>',
    'to' => [
        '<string>'
    ],
    'subject' => '<string>',
    'html' => '<string>',
    'text' => '<string>',
    'cc' => [
        '<string>'
    ],
    'bcc' => [
        '<string>'
    ],
    'reply_to' => [
        '<string>'
    ],
    'headers' => [
        
    ],
    'attachments' => [
        [
                
        ]
    ],
    'idempotencyKey' => '<string>',
    'tracking' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "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.example.com/emails"

	payload := strings.NewReader("{\n  \"from\": \"<string>\",\n  \"to\": [\n    \"<string>\"\n  ],\n  \"subject\": \"<string>\",\n  \"html\": \"<string>\",\n  \"text\": \"<string>\",\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"reply_to\": [\n    \"<string>\"\n  ],\n  \"headers\": {},\n  \"attachments\": [\n    {}\n  ],\n  \"idempotencyKey\": \"<string>\",\n  \"tracking\": {}\n}")

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

	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.example.com/emails")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"<string>\",\n  \"to\": [\n    \"<string>\"\n  ],\n  \"subject\": \"<string>\",\n  \"html\": \"<string>\",\n  \"text\": \"<string>\",\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"reply_to\": [\n    \"<string>\"\n  ],\n  \"headers\": {},\n  \"attachments\": [\n    {}\n  ],\n  \"idempotencyKey\": \"<string>\",\n  \"tracking\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"<string>\",\n  \"to\": [\n    \"<string>\"\n  ],\n  \"subject\": \"<string>\",\n  \"html\": \"<string>\",\n  \"text\": \"<string>\",\n  \"cc\": [\n    \"<string>\"\n  ],\n  \"bcc\": [\n    \"<string>\"\n  ],\n  \"reply_to\": [\n    \"<string>\"\n  ],\n  \"headers\": {},\n  \"attachments\": [\n    {}\n  ],\n  \"idempotencyKey\": \"<string>\",\n  \"tracking\": {}\n}"

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

{
  "id": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "to": "<string>",
  "subject": "<string>",
  "from": "<string>"
}

Description

Send a transactional email using Sendly. This is the most common and versatile endpoint.

Parameters

from

string

required

Email address of the sender. Must be a verified domain in your account. Examples: noreply@yourdomain.com, no-reply@mail.yourdomain.com

string | string[]

required

Email address(es) of the recipient. Can be a string or array.

subject

string

required

Email subject. Maximum 255 characters.

html

string

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

text

string

Plain text content. Used as fallback if html is not provided.

string | string[]

CC recipient(s). Visible to all recipients.

bcc

string | string[]

BCC recipient(s). Visible only on server.

reply_to

string | string[]

Reply-to address(es).

headers

object

Custom headers. Example: {"X-Custom-Header": "value"}

attachments

array

Array of file attachments:

filename (string): File name
content (string | Buffer): Base64 encoded content
content_type (string): MIME type (e.g., application/pdf)
cid (string): Content ID for inline images

idempotencyKey

string

Unique key to prevent duplicates. Resending with the same key returns the previous response.

tracking

object

Tracking options:

open (boolean): Track opens. Default: false
click (boolean): Track clicks. Default: false

Response

string

Unique email ID. Use to check status later.

status

string

Current email status.

created_at

string

ISO 8601 timestamp of creation.

string

Recipient email address.

subject

string

Email subject.

from

string

Sender email address.

Examples

Basic Email

curl -X POST https://api.usesendly.app/v1/emails \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Welcome!",
    "html": "<h1>Hello!</h1><p>Thanks for signing up.</p>"
  }'

import { Sendly } from '@sendlyapp/sdk'

const client = new Sendly('se_your_api_key')

const response = await client.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
})

console.log('Email ID:', response.id)

import nodemailer from 'nodemailer'

const transporter = nodemailer.createTransport({
  host: 'smtp.usesendly.app',
  port: 587,
  secure: false,
  auth: {
    user: 'se_your_api_key',
    pass: 'se_your_api_key'
  }
})

await transporter.sendMail({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
})

Multiple Recipients

curl -X POST https://api.usesendly.app/v1/emails \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": ["user1@example.com", "user2@example.com"],
    "cc": "admin@yourdomain.com",
    "subject": "Important Notice",
    "html": "<p>This is important...</p>"
  }'

await client.emails.send({
  from: 'noreply@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: 'admin@yourdomain.com',
  subject: 'Important Notice',
  html: '<p>This is important...</p>'
})

await transporter.sendMail({
  from: 'noreply@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: 'admin@yourdomain.com',
  subject: 'Important Notice',
  html: '<p>This is important...</p>'
})

With Tracking

curl -X POST https://api.usesendly.app/v1/emails \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Newsletter",
    "html": "<h1>Newsletter</h1><p>Content...</p>",
    "tracking": {
      "open": true,
      "click": true
    }
  }'

const response = await client.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Newsletter',
  html: '<h1>Newsletter</h1><p>Content...</p>',
  tracking: {
    open: true,
    click: true
  }
})

await transporter.sendMail({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Newsletter',
  html: '<h1>Newsletter</h1><p>Content...</p>',
  headers: {
    'X-Track-Opens': 'true',
    'X-Track-Clicks': 'true'
  }
})

With Attachments

curl -X POST https://api.usesendly.app/v1/emails \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Your Document",
    "html": "<p>See attached PDF</p>",
    "attachments": [
      {
        "filename": "document.pdf",
        "content": "JVBERi0xLjQKJeLj...",
        "content_type": "application/pdf"
      }
    ]
  }'

import fs from 'fs'

const pdfContent = fs.readFileSync('document.pdf')
const base64 = pdfContent.toString('base64')

await client.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your Document',
  html: '<p>See attached PDF</p>',
  attachments: [
    {
      filename: 'document.pdf',
      content: base64,
      content_type: 'application/pdf'
    }
  ]
})

import fs from 'fs'

await transporter.sendMail({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your Document',
  html: '<p>See attached PDF</p>',
  attachments: [
    {
      filename: 'document.pdf',
      path: 'document.pdf'
    }
  ]
})

With Idempotency Key

curl -X POST https://api.usesendly.app/v1/emails \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "Payment Confirmation",
    "html": "<p>Your payment was processed</p>",
    "idempotencyKey": "payment-123"
  }'

await client.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Payment Confirmation',
  html: '<p>Your payment was processed</p>',
  idempotencyKey: 'payment-123'
})

await transporter.sendMail({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Payment Confirmation',
  html: '<p>Your payment was processed</p>',
  messageId: 'payment-123'
})

Error Handling

import { SendlyError } from '@sendlyapp/sdk'

try {
  await client.emails.send({
    from: 'noreply@invalid.com',
    to: 'user@example.com',
    subject: 'Email',
    html: '<p>Content</p>'
  })
} catch (error) {
  if (error instanceof SendlyError) {
    console.error(`Error ${error.status}: ${error.message}`)
  }
}

# Will return 400 Bad Request with error details
curl -X POST https://api.usesendly.app/v1/emails \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invalid-email",
    "to": "user@example.com"
  }'

# Response:
# {
#   "code": "INVALID_EMAIL",
#   "message": "The email address is invalid",
#   "status": 400
# }

Limits

Recipients per email: Maximum 10,000
Attachment size: Maximum 25 MB per email
Send rate: 1,000 emails/minute
Auto-retries: Up to 5 times for temporary errors

Notes

The from address must be a verified domain
Emails are queued for immediate processing
Initial status is always QUEUED
Use idempotencyKey for critical transactions
Open tracking requires an image in the email

Need help? Contact support@usesendly.app

SDK Integration List Emails

​Description

​Parameters

​Response

​Examples

​Basic Email

​Multiple Recipients

​With Tracking

​With Attachments

​With Idempotency Key

​Error Handling

​Limits

​Notes

Description

Parameters

Response

Examples

Basic Email

Multiple Recipients

With Tracking

With Attachments

With Idempotency Key

Error Handling

Limits

Notes