Apimend Mail docs
Email for AI-native apps. One API to send email, with idempotent retries, guardrails, and signed events.
https://app.apimend.com. For local development it is http://127.0.0.1:4000.Quickstart
- Create a workspace at /dashboard or
/signup. You get an API key. - Store the key as
APIMEND_KEYin your environment. - 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.
SEND_MODE=mock, the token is also returned in the response so you can test without a real inbox.Send email
POST /v1/send
| Field | Type | Notes |
|---|---|---|
from | string | Verified sender address. Required. |
to | string | string[] | One or many recipients. Required. |
subject | string | Required unless using a template. |
html | string | HTML body. A plain-text part is generated automatically. |
text | string | Optional plain-text body. |
replyTo | string | Optional reply-to address. |
template | string | Template id. Subject and body come from the template. |
templateData | object | Values for {{tokens}}. |
idempotencyKey | string | Deduplicates repeated API requests with the same key; ambiguous provider outcomes are not automatically resent. |
attachments | array | { filename, content (base64), contentType }. |
track | boolean | Default true. Set false to disable open and click tracking. |
scheduledAt | string | ISO 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" }
]
}
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"}'
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
| Plan | Price | Emails / month | Requests / min |
|---|---|---|---|
| Free | $0 | 4,000 | 60 |
| Starter | $15 | 60,000 | 300 |
| Growth | $60 | 300,000 | 600 |
| Scale | $180 | 1,200,000 | 1,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
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Missing CSRF header or cross-origin request |
402 | Plan limit reached |
422 | Invalid input, suppressed recipient, or bad template |
429 | Rate limit or daily cap exceeded |
502 | Provider send failed |
Errors return JSON: { "error": "message" }.
Ready to send?
Create a workspace and send your first email in minutes.