Apimend Mail / Docs
Open console

Apimend Mail docs

Email for AI-native apps. One API to send email, with idempotent retries, guardrails, and signed events.

Base URL: https://app.apimend.com. For local development it is http://127.0.0.1:4000.

Quickstart

  1. Create a workspace at /dashboard or /signup. You get an API key.
  2. Store the key as APIMEND_KEY in your environment.
  3. Verify a domain you own in the console, then send your first email from an address on that domain.
import { ApimendMail } from "apimend-mail";

const mail = new ApimendMail({ apiKey: process.env.APIMEND_KEY! });

await mail.send({
  from: "hello@you.com",
  to: "user@example.com",
  subject: "Welcome",
  html: "<h1>You are in</h1>",
});

The API returns 202 { id, status: "queued" }. A worker sends it. Poll GET /v1/emails/:id for sent.

Authentication

Send the API key as a bearer token:

Authorization: Bearer am_live_...

The dashboard uses a session cookie instead. Both resolve to the same workspace. Keys are hashed, shown once, and can be revoked any time.

Verification and password reset

Request a verification email with POST /v1/auth/verify/request, then confirm with POST /v1/auth/verify and { token }. Password reset works the same way through /v1/auth/reset/request and /v1/auth/reset.

While SEND_MODE=mock, the token is also returned in the response so you can test without a real inbox.

Send email

POST /v1/send

FieldTypeNotes
fromstringVerified sender address. Required.
tostring | string[]One or many recipients. Required.
subjectstringRequired unless using a template.
htmlstringHTML body. A plain-text part is generated automatically.
textstringOptional plain-text body.
replyTostringOptional reply-to address.
templatestringTemplate id. Subject and body come from the template.
templateDataobjectValues for {{tokens}}.
idempotencyKeystringDeduplicates repeated API requests with the same key; ambiguous provider outcomes are not automatically resent.
attachmentsarray{ filename, content (base64), contentType }.
trackbooleanDefault true. Set false to disable open and click tracking.
scheduledAtstringISO timestamp. Delays the send until that time.
curl https://app.apimend.com/v1/send \
  -H "Authorization: Bearer $APIMEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@you.com",
    "to": "user@example.com",
    "subject": "Welcome",
    "html": "<h1>You are in</h1>"
  }'

Idempotency

Pass idempotencyKey in the body, or an Idempotency-Key header. A repeated request with the same key returns the original email instead of sending again. Use your agent run id.

curl https://app.apimend.com/v1/send \
  -H "Authorization: Bearer $APIMEND_KEY" \
  -H "Idempotency-Key: run_42" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Batch and scheduled sends

Send up to 100 emails in one request with POST /v1/send/batch:

POST /v1/send/batch
{
  "emails": [
    { "from": "a@you.com", "to": "x@example.com", "subject": "Hi", "html": "..." }
  ]
}

To delay a single send, set scheduledAt to an ISO timestamp. The job stays queued until then.

Attachments

Send up to 10 attachments, 10MB total. Content is base64.

{
  "attachments": [
    { "filename": "invoice.pdf", "content": "JVBERi0...", "contentType": "application/pdf" }
  ]
}
Attachments send through Amazon SES using raw MIME. Up to 10 files, 10MB total.

Templates

POST /v1/templates with { name, subject, html, text?, category?, blocks? }. Use {{token}} for variables. Update or archive with PATCH /v1/templates/:id; duplicate with POST /v1/templates/:id/duplicate. Preview sample data with POST /v1/templates/:id/preview. Revisions are available at GET /v1/templates/:id/versions; restore one with POST /v1/templates/:id/versions/:versionId/restore. Archived templates cannot be used to send.

The dashboard includes a canvas-first visual editor with starter transactional templates, headings, text, buttons, HTTPS images, dividers, block styles, desktop/mobile preview, raw HTML mode, token/sample-data validation, test send, categories, search, archive, and revision rollback. Visual blocks are optional; existing raw HTML templates remain editable. Button and image blocks support optional alignment, color, and sizing properties.

Image blocks can upload PNG, JPEG, GIF, or WebP files up to 5 MB through POST /v1/template-assets. The API validates and re-encodes the first frame before storing it; animated images become still images. Configure TEMPLATE_ASSETS_BUCKET, TEMPLATE_ASSETS_PUBLIC_BASE_URL, an IAM role, and public HTTPS image delivery (normally through CloudFront).

curl https://app.apimend.com/v1/templates \
  -H "Authorization: Bearer $APIMEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"welcome","subject":"Welcome {{name}}","html":"<h1>Hi {{name}}</h1>"}'

Then send with:

{
  "from": "hello@you.com",
  "to": "user@example.com",
  "template": "<template id>",
  "templateData": { "name": "Sufiyan" }
}

List and get

GET /v1/emails?limit=25&offset=0 returns the log for your workspace. GET /v1/emails/:id returns one email with status, provider, and error.

Domains

POST /v1/domains with { domain }. Add the returned Apimend ownership TXT record, then verify with POST /v1/domains/:domain/verify. After ownership is verified, request SES identity records with POST /v1/domains/:domain/ses and check provider status with GET on the same path.

curl https://app.apimend.com/v1/domains \
  -H "Authorization: Bearer $APIMEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.yourcompany.com"}'
Verification runs real DNS TXT lookups when DOMAIN_VERIFY_MODE=dns. In development it simulates success.

Suppressions

POST /v1/suppressions with { email, reason }. Suppressed addresses are blocked before a job is queued. Bounces and complaints from SES are added automatically through /v1/ses/notifications.

Tracking

When tracking is on, an open pixel and tracked links are added. Counts appear in GET /v1/stats as opens and clicks.

  • GET /t/open.gif?e=<emailId> records an open.
  • GET /t/click?e=<emailId>&u=<url> records a click and redirects.

Unsubscribe

Every tracked email gets a signed unsubscribe link. Visiting it adds a suppression for the recipient. You do not need to build anything.

Webhooks

POST /v1/webhooks with { url, events, headers? }. Events are email.sent, email.failed, or "*".

Each delivery is signed:

X-Apimend-Signature: t=<unix>,v1=<hmac-sha256(secret, t + "." + body)>

Verify with the SDK. Reject if it returns false.

import { verifyWebhook } from "apimend-mail";

const ok = verifyWebhook({
  secret: process.env.WH_SECRET!,
  payload: rawBody,
  signature: req.headers["x-apimend-signature"] as string,
});
if (!ok) return res.status(400).end();

Failed deliveries retry with backoff. See the log at GET /v1/deliveries. Rotate a secret with PATCH /v1/webhooks/:id and { "rotateSecret": true }.

SDK

import { ApimendMail, verifyWebhook } from "apimend-mail";

const mail = new ApimendMail({ apiKey: process.env.APIMEND_KEY! });

await mail.send({ from, to, subject, html });   // 202 queued
await mail.get(id);                               // one email
await mail.list({ limit: 20 });                // recent
await mail.templates();                          // list templates

Rate limits and plans

PlanPriceEmails / monthRequests / min
Free$04,00060
Starter$1560,000300
Growth$60300,000600
Scale$1801,200,0001,200

Every plan includes the agent tool schema, idempotent sends, per-agent API keys, guardrails (daily caps and plan rate limits), and signed events. Requests are rate limited per workspace by plan. You can also set a daily send cap. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Going over returns 429. Going over the plan returns 402.

Billing

POST /v1/billing/checkout with { plan } creates a Dodo Payments Checkout Session for a configured product. POST /v1/billing/portal opens the linked customer's Dodo portal. Signed Dodo subscription events update plan and billing status through /v1/billing/webhook.

Export, delete, and inbound

GET /v1/account/export returns a JSON bundle of workspace data. DELETE /v1/account removes the workspace and its data.

POST /v1/inbound stores an inbound message (placeholder), and GET /v1/inbound lists them.

Errors

StatusMeaning
401Missing or invalid API key
403Missing CSRF header or cross-origin request
402Plan limit reached
422Invalid input, suppressed recipient, or bad template
429Rate limit or daily cap exceeded
502Provider send failed

Errors return JSON: { "error": "message" }.

Ready to send?

Create a workspace and send your first email in minutes.

Open console