Documentation

Getting started

Three steps from zero to your first delivered email.

Verify a domain

Add a domain and you get three CNAME records that set up email signing (DKIM). Create them at your DNS provider, and the dashboard checks automatically every 15 seconds until they resolve. Verification usually completes within minutes, but DNS propagation can take up to 48 hours.

Once verified, you can send from any address at that domain - and at its subdomains. Verifying example.com also lets you send from news.example.com. The Free plan includes 1 sending domain; paid plans include more (see Quotas and plans).

Your records and live verification status are on the Domains page.

Send via HTTP API

Send by POSTing JSON to https://api.sendscape.ai/v1/emails with your API key as a bearer token: Authorization: Bearer YOUR_API_KEY. Keys start with ss_ and are created on the API Keys page.

Request fields

Example request

curl -X POST https://api.sendscape.ai/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from Sendscape",
    "html": "<p>It works!</p>"
  }'

Success response

Accepted sends return 202. The id is the send-log entry you can find under Email Metrics.

HTTP/1.1 202 Accepted

{
  "id": 42,
  "message_id": "0107019064ab1234-56c78d90-...",
  "status": "accepted"
}

Errors

Errors use a consistent envelope: an error machine code plus a human-readable message.

HTTP/1.1 422 Unprocessable Content

{
  "error": "domain_not_verified",
  "message": "The sending domain 'example.com' is not verified for this account."
}

Advanced fields

cc, bcc, a reply-to list, custom headers, tags, an inline attachment and an Idempotency-Key, all in one request. Attachments are capped at 10 MB decoded per message.

curl -X POST https://api.sendscape.ai/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-receipt" \
  -d '{
    "from": "Acme <billing@yourdomain.com>",
    "to": ["customer@example.com"],
    "cc": ["accounts@example.com"],
    "bcc": "archive@yourdomain.com",
    "reply_to": ["support@yourdomain.com"],
    "subject": "Receipt for order 42",
    "html": "<p>Thanks! <img src=\"cid:logo\"></p>",
    "headers": { "X-Entity-Ref-ID": "order-42" },
    "tags": [{ "name": "category", "value": "receipt" }],
    "attachments": [{ "filename": "logo.png", "content": "iVBORw0KGgo...", "content_type": "image/png", "content_id": "logo" }]
  }'

Idempotency

Add an Idempotency-Key header (any string, unique per logical send) and a retried request returns the original outcome instead of sending twice. Remembered for 24 hours per API key; quota and pause errors are not remembered, so the same key can be retried later.

POST /v1/emails
Idempotency-Key: order-42-receipt

# first call -> 202 {"id": 42, ...}
# same key + same body within 24 h -> the same 202 body, plus:
Idempotency-Replayed: true
# same key + a different body -> 422 idempotency_key_reused

Retrieve and list

GET /v1/emails/{id} returns the email object; GET /v1/emails lists yours newest first with a cursor. Both need a full-access key.

HTTP/1.1 200 OK

{
  "id": 42,
  "message_id": "0107019064ab1234-56c78d90-...",
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "cc": [],
  "bcc": [],
  "reply_to": ["support@yourdomain.com"],
  "subject": "Your receipt",
  "tags": [{ "name": "category", "value": "receipt" }],
  "status": "delivered",
  "error": null,
  "channel": "api",
  "created_at": "2026-09-07T10:15:02+08:00",
  "last_event_at": "2026-09-07T10:15:09+08:00",
  "bounce_type": null,
  "opened_at": "2026-09-07T10:21:40+08:00",
  "clicked_at": null,
  "open_count": 1,
  "click_count": 0
}

Send a batch

POST /v1/emails/batch takes an array of up to 100 messages (no attachments). Every message is validated before any is sent; a valid batch is sent in order with one result per message.

POST /v1/emails/batch
Idempotency-Key: nightly-2026-09-07

[
  { "from": "hello@yourdomain.com", "to": ["a@example.com"], "subject": "Hi A", "text": "..." },
  { "from": "hello@yourdomain.com", "to": ["b@example.com"], "subject": "Hi B", "text": "..." }
]

Sandbox addresses

Exercise the whole pipeline - log rows, statuses, webhooks - without real mail or quota. Works from any verified domain, or from onboarding@sendscape.ai before you have one.

API key permissions

A key is full-access by default. A sending-only key can call the send endpoints but not read your log, and a key can be bound to one sending domain.

Send via SMTP

Anything that speaks SMTP - Laravel, WordPress, legacy apps, IoT devices - can send through Sendscape without code changes. Create a credential on the SMTP Credentials page and plug in these settings:

SMTP goes through the same pipeline as the HTTP API: the from domain must be verified, suppressed recipients are rejected, and sends count against the same quota.

MAIL_MAILER=smtp
MAIL_HOST=smtp.sendscape.ai
MAIL_PORT=587
MAIL_USERNAME=YOUR_SMTP_USERNAME
MAIL_PASSWORD=••••••••   # shown once when you create the credential
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=hello@yourdomain.com

Connect n8n

Use Sendscape in an n8n workflow with built-in nodes - no custom node required. Either the HTTP Request node with an API key, or the Send Email node with an SMTP credential.

n8n → "HTTP Request" node
─────────────────────────────────
Method:          POST
URL:             https://api.sendscape.ai/v1/emails
Authentication:  Generic Credential → Header Auth
  • Name:        Authorization
  • Value:       Bearer YOUR_API_KEY
Send Body:       ON   (Body Content Type: JSON)
Specify Body:    Using JSON

JSON body:
{
  "from": "hello@yourdomain.com",
  "to": ["recipient@example.com"],
  "subject": "Hello from n8n",
  "html": "<p>Sent from an n8n workflow.</p>"
}

Webhooks

Register an HTTPS endpoint under Webhooks and Sendscape POSTs a signed JSON event every time one of your emails moves - delivered, bounced, complained and more. Answer any 2xx within 10 seconds; failures are retried for about a day.

A delivery

POST https://example.com/webhooks/sendscape
Content-Type: application/json
User-Agent: Sendscape-Webhooks/1.0
Sendscape-Event: email.bounced
Sendscape-Event-Id: evt_3f9c2a1b7d4e5f60718293a4b5
Sendscape-Delivery-Id: 1187
Sendscape-Timestamp: 1789000000
Sendscape-Signature: v1=8a4d1c...

{
  "type": "email.bounced",
  "id": "evt_3f9c2a1b7d4e5f60718293a4b5",
  "created_at": "2026-09-07T10:15:09+08:00",
  "data": {
    "id": 42,
    "message_id": "0107019064ab1234-56c78d90-...",
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "cc": [],
    "bcc": [],
    "reply_to": [],
    "subject": "Your receipt",
    "tags": [{ "name": "category", "value": "receipt" }],
    "status": "bounced",
    "error": null,
    "channel": "api",
    "created_at": "2026-09-07T10:15:02+08:00",
    "last_event_at": "2026-09-07T10:15:09+08:00",
    "bounce_type": "Permanent",
    "opened_at": null,
    "clicked_at": null,
    "open_count": 0,
    "click_count": 0,
    "bounce": {
      "type": "Permanent",
      "sub_type": "General",
      "diagnostic_code": "smtp; 550 5.1.1 user unknown",
      "recipient": "user@example.com",
      "timestamp": "2026-09-07T02:15:09.000Z"
    }
  }
}

Verify the signature

Sendscape-Signature is v1= plus HMAC-SHA256 over {timestamp}.{raw body} with your endpoint secret. Hash the exact bytes you received, compare in constant time, and reject timestamps more than 5 minutes off.

$secret = getenv('SENDSCAPE_WEBHOOK_SECRET');
$body = file_get_contents('php://input');           // the raw bytes, never re-encoded
$timestamp = $_SERVER['HTTP_SENDSCAPE_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_SENDSCAPE_SIGNATURE'] ?? '';

$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// $event['type'] e.g. "email.bounced"; $event['data'] is the email object
http_response_code(200);

Retries

After 50 consecutive final failures the endpoint is switched off and you are emailed; re-enable it from the dashboard once it is reachable. Logs are kept 30 days on Free and 90 on paid plans; webhook delivery history for 30.

Broadcasts (marketing)

Broadcasts send one email to your whole audience - newsletters, promos, announcements. Everything happens in the dashboard (no API needed): build your list under Contacts, compose and send under Broadcasts.

Merge tags

Tags work in the subject and the body. Contact values are HTML-escaped in the body, so a name like <b>Ana</b> shows as text rather than becoming markup; a fallback is your own template and is left as written. An unknown tag with no fallback renders as nothing, never as raw braces.

Unsubscribe, handled for you

Every broadcast automatically carries an unsubscribe footer link and the one-click unsubscribe header that Gmail and Yahoo require from bulk senders - there is nothing to configure. When someone unsubscribes, future broadcasts skip them automatically, but they still receive your transactional email (receipts, OTPs) - unsubscribes and the suppression list are deliberately separate. A recipient who marks a broadcast as spam is unsubscribed automatically too.

Rules of the road

• Broadcasts go only to subscribed contacts, deduplicated across groups.
• A test send is a real email through your domain (it counts like any send for reputation) but writes no recipient row and never spends the free-tier monthly cap.
• If you hold more contacts than your marketing plan allows (for example after a downgrade), adding contacts and sending broadcasts pause until you upgrade or trim the list - contacts are never deleted.
• The free marketing tier sends up to 4,000 broadcast emails per month and adds a small “Sent with Sendscape” line to the footer - both lifted on paid marketing plans.

Plans, quotas and extras

Transactional plans

Quotas count messages, not recipients - one send to 50 addresses uses 1 from your quota (and all 50 share the same To field; see the to field above). The daily quota resets at midnight (Malaysia time); the monthly quota resets on your billing anniversary, not the calendar month. Sends over quota return 429 quota_exceeded and nothing is queued - retry after the reset. Manage your plan under Usage & Billing.

Marketing plans

Marketing is priced by contacts stored, not emails sent - broadcasts never consume your transactional quota. The two plans are separate and mix freely: free transactional with a paid marketing plan works, and so does the reverse.

Extra emails (pay-as-you-go)

On paid transactional plans you can keep sending past your monthly limit: enable Extra emails under Usage & Billing → Extras, and each additional 1,000 emails deducts RM 4.00 from your credits automatically. Your daily limit always applies, and nothing is charged unless you opt in. The free plan is a hard stop at its monthly quota.

Send statuses

Every message gets a status on the Email Metrics page. Most sends start as Accepted and move on once the receiving server reports back.

The Failed tab lists both Failed and Rejected messages - they are the two ways a send can not go out. Click any row to open its details, which include the exact reason. The codes behind a rejection are the same ones the API returns: see Errors.

Bounced and Complained addresses go straight onto your suppression list - see Suppressions and deliverability for what that means for your account.

Broadcast emails appear here too (channel broadcast). Each broadcast's own page adds two fan-out states you will not see in Email Metrics: Pending (queued, not yet sent) and Skipped (the contact unsubscribed or was suppressed by the time we reached them).

Suppressions and deliverability

When an email hard-bounces or the recipient marks it as spam, that address is automatically added to your suppression list. Later sends to it are rejected with recipient_suppressed instead of being silently dropped, so your logs stay honest. Review and manage the list under Suppressions.

To protect deliverability for everyone, accounts with a bounce rate above 5% or a complaint rate above 0.1% (measured after 50 sends) are paused automatically.

Keeping your rates healthy is mostly list hygiene:

• Send only to recipients who opted in - never to purchased or scraped lists.
• Remove addresses that have not engaged in months before large sends.
• Include a plain-text part alongside your HTML.
• Use a subdomain (like mail.yourdomain.com) for transactional mail to isolate reputation.
• Broadcasts count toward the same bounce and complaint rates - a spam complaint on a newsletter hurts your account exactly like one on a receipt (and auto-unsubscribes that contact).

Using AI coding assistants

If you build with Claude, Cursor or a similar assistant, install the Sendscape skill and it will write integration code against the real API instead of guessing. The bundle is generated from this page, so the endpoint, request fields and error codes are always the ones documented above.

Download sendscape-skill.zip

# Install the Sendscape skill into your project
mkdir -p .claude/skills
curl -L https://sendscape.ai/sendscape-skill.zip -o /tmp/sendscape-skill.zip
unzip -o /tmp/sendscape-skill.zip -d .claude/skills

# Or install it for every project on this machine:
#   unzip -o /tmp/sendscape-skill.zip -d ~/.claude/skills

# Then just ask, and it loads on its own:
#   "send a welcome email with Sendscape when a user signs up"