Skip to content

Developers

Send your first email in five minutes.

One REST endpoint for transactional and marketing email, and an MCP server so your AI assistant can use it too.

Quickstart

  1. Step 1

    Verify a domain

    In the app, open Deliverability → Domains, add your domain and copy the DNS records it shows (DKIM, MAIL FROM, DMARC).

  2. Step 2

    Create an API key

    Under Developers → API keys. Keys start with rs_live_ and are shown once — store yours as a secret.

  3. Step 3

    Send

    POST to /api/v1/emails. You get one result per recipient, and each email costs one credit.

cURL
curl https://app.rampsend.com/api/v1/emails \  -H "Authorization: Bearer rs_live_…" \  -H "Content-Type: application/json" \  -d '{    "from": "Acme <hello@acme.eu>",    "to": "ada@example.com",    "subject": "Welcome to Acme",    "html": "<p>Hi Ada, thanks for signing up.</p>"  }'
Node.js (fetch)
const res = await fetch("https://app.rampsend.com/api/v1/emails", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RAMPSEND_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": "welcome-user-8812",  },  body: JSON.stringify({    from: "Acme <hello@acme.eu>",    to: ["ada@example.com", "grace@example.com"],    subject: "Your weekly digest",    html: "<p>Here is what happened this week.</p>",    tags: { type: "digest" },    unsubscribe_header: true,  }),});const { data } = await res.json(); // one result per recipient
Python (requests)
import os, requestsres = requests.post(    "https://app.rampsend.com/api/v1/emails",    headers={"Authorization": f"Bearer {os.environ['RAMPSEND_API_KEY']}"},    json={        "from": "Acme <hello@acme.eu>",        "to": "ada@example.com",        "subject": "Your password reset link",        "text": "Reset your password: https://acme.eu/reset/…",        "track_clicks": False,    },)print(res.json()["status"])  # "queued"

Authentication

Send your API key as a Bearer token on every request. Base URL: https://app.rampsend.com/api/v1.

Header
Authorization: Bearer rs_live_…

Keys belong to one workspace. New keys get the send scope; add read to look emails up, or full for everything. Revoke a key at any time in the app — it stops working at once. Never put a key in browser or mobile code.

Send an email

POST /api/v1/emails

Body fields (JSON):

FieldTypeDescription
fromrequiredstringSender, as hello@acme.eu or Acme <hello@acme.eu>. Must be on a domain you have verified.
torequiredstring | string[]One address or up to 50. Each recipient gets their own copy, with its own id, status and tracking. Duplicates are sent once.
subjectrequiredstringUp to 998 characters.
htmlstringHTML body. Provide html, text or both. If you send only HTML, a plain-text part is generated for you.
textstringPlain-text body.
reply_tostring | string[]Up to 5 reply-to addresses.
headersobjectExtra headers as { "X-Entity-Ref": "…" }. Standard headers such as From, To, Subject and Message-ID can’t be overridden.
tagsobjectYour own key–value labels, kept with the message (keys: letters, digits, _ and -).
track_opensbooleanDefault true for HTML email. Set false to skip the open pixel.
track_clicksbooleanDefault true for HTML email. Set false to leave links untouched — a good idea for password resets and sign-in links.
unsubscribe_headerbooleanAdds RFC 8058 one-click List-Unsubscribe headers. Recommended for anything that isn’t strictly transactional.

Recipients on your suppression list — past hard bounces, complaints and unsubscribes — are skipped and not charged. Credit for every other recipient is taken when you send, and returned if the email can’t be handed to the mail server.

Response

200 with one entry per recipient in data. A recipient’s status is queued (accepted; it usually goes out within seconds), sent, suppressed or failed (with an error message). Suppressed and failed emails are never charged. Use the id with Look up an email to follow a queued email to delivered. For a single recipient, id and status are also at the top level. If every recipient failed, the status code is 502.

One recipient
{  "id": "6f1c2a9e-4b7d-4c1e-9a53-2d8f0e7b1c44",  "status": "queued",  "data": [    { "id": "6f1c2a9e-4b7d-4c1e-9a53-2d8f0e7b1c44", "to": "ada@example.com", "status": "queued" }  ]}
Several recipients
{  "data": [    { "id": "0b3e…", "to": "ada@example.com", "status": "queued" },    { "id": "9d71…", "to": "grace@example.com", "status": "suppressed" }  ]}

Look up an email

GET /api/v1/emails/:id

Delivery status and engagement for one email. Status moves through queued, sent, delivered — or ends at bounced, complained, failed or suppressed. Needs the read scope.

Request
curl https://app.rampsend.com/api/v1/emails/6f1c2a9e-4b7d-4c1e-9a53-2d8f0e7b1c44 \  -H "Authorization: Bearer rs_live_…"
Response
{  "id": "6f1c2a9e-4b7d-4c1e-9a53-2d8f0e7b1c44",  "kind": "transactional",  "to": "ada@example.com",  "from": "hello@acme.eu",  "subject": "Welcome to Acme",  "tags": {},  "status": "delivered",  "bounce": null,  "created_at": "2026-11-19T10:02:11Z",  "sent_at": "2026-11-19T10:02:12Z",  "delivered_at": "2026-11-19T10:02:14Z",  "opened_at": "2026-11-19T10:09:40Z",  "clicked_at": null,  "opens": 1,  "clicks": 0,  "unsubscribed_at": null}

Events

POST /api/v1/events · POST /api/v1/events/bulk · GET /api/v1/metrics

Track what people do in your product — a purchase, a trial start, a page view — so segments and automations can use it. Each event names a metric (created on first use) and a profile, matched by external_id, then email, then phone; a new profile needs an email and starts without marketing consent. Add unique_id and a repeat is counted as a duplicate, not a second event. /events/bulk takes {"events": [...]} with up to 100 events and reports errors per event by index. Both answer 202 and need the contacts scope. GET /metrics (read) lists your custom metrics and Rampsend's email metrics (Received, Opened, Clicked, Bounced, Marked as Spam, Unsubscribed).

Request
curl https://app.rampsend.com/api/v1/events \  -H "Authorization: Bearer rs_live_…" \  -H "Content-Type: application/json" \  -d '{    "metric": "Placed Order",    "profile": { "email": "ada@example.com", "external_id": "user-8812", "first_name": "Ada" },    "properties": { "order_id": "1042", "items": ["Notebook"], "total": 49.5 },    "value": 49.5,    "value_currency": "EUR",    "time": "2026-11-19T10:15:00Z",    "unique_id": "order-1042"  }'
202 Accepted
{ "inserted": 1, "duplicates": 0, "errors": [] }

Profiles

POST /api/v1/profiles · GET /api/v1/profiles?email= · GET · PATCH /api/v1/profiles/:id

A profile is one person: email, phone (E.164), external id, name, organization, location and any custom properties (merged on update; send null to remove one). POST creates or updates by identifier and answers 201 or 200. Set email_consent to subscribed or unsubscribed only when the person told you so — it drives who can receive marketing. Writes need contacts; reads need read.

Create or update, then look up
curl https://app.rampsend.com/api/v1/profiles \  -H "Authorization: Bearer rs_live_…" \  -H "Content-Type: application/json" \  -d '{    "email": "ada@example.com",    "first_name": "Ada",    "country": "LT",    "properties": { "plan": "pro", "seats": 5 },    "email_consent": "subscribed",    "email_consent_source": "signup form"  }'curl "https://app.rampsend.com/api/v1/profiles?email=ada@example.com" -H "Authorization: Bearer rs_live_…"

Lists

GET · POST /api/v1/lists · POST · DELETE /api/v1/lists/:id/profiles

Lists are static groups you add people to. Add or remove up to 1,000 at a time by profile_ids and/or emails. Unknown emails come back in not_found; pass "create_missing": true to create them (without marketing consent).

Add to a list
curl https://app.rampsend.com/api/v1/lists/LIST_ID/profiles \  -H "Authorization: Bearer rs_live_…" \  -H "Content-Type: application/json" \  -d '{ "emails": ["ada@example.com", "grace@example.com"] }'
Response
{ "added": 1, "already_members": 1, "created_profiles": 0, "not_found": [], "invalid_emails": [] }

Segments

GET · POST /api/v1/segments · GET /api/v1/segments/:id/profiles · POST /api/v1/segments/count

Segments are dynamic groups defined by conditions and refreshed every 15 minutes. A definition is a list of groups: groups are AND-ed, the conditions inside a group are OR-ed. Conditions cover what someone has done (a metric at least / at most / exactly / zero times, over a timeframe, optionally filtered by event properties), profile properties (text, number, date, true/false and list operators), list and segment membership, EU residence and whether they can receive email marketing. POST /segments/count returns the live count for a draft definition; GET /segments/:id/profiles pages through members with ?after=.

Create a segment
curl https://app.rampsend.com/api/v1/segments \  -H "Authorization: Bearer rs_live_…" \  -H "Content-Type: application/json" \  -d '{    "name": "Engaged EU buyers",    "definition": {      "version": 1,      "groups": [        { "conditions": [          { "type": "metric", "metric_id": "METRIC_ID", "op": "at_least", "count": 1,            "timeframe": { "kind": "in_last", "value": 30, "unit": "day" } }        ] },        { "conditions": [ { "type": "eu", "in": true } ] },        { "conditions": [ { "type": "consent", "channel": "email", "can": true } ] }      ]    }  }'

Automations

GET · POST /api/v1/flows · GET /api/v1/flows/:id · PUT /api/v1/flows/:id/draft · POST /api/v1/flows/:id/publish · POST /api/v1/flows/:id/status · GET · PUT /api/v1/flows/:id/messages/:nodeId · GET · POST /api/v1/flows/:id/runs · POST /api/v1/flows/:id/simulate · GET /api/v1/flows/:id/report · GET · DELETE /api/v1/flow-runs/:id · GET /api/v1/flow-templates

An automation (flow) is one JSON document: a trigger (an event, joining a list or segment, a date property, or an API call), then steps — emails, delays, waits for an event, splits, random splits, profile updates and list changes. The API reads and writes the same document the editor shows. POST /flows creates a draft from a document or a template (GET /flow-templates); PUT /flows/:id/draft replaces it, with If-Match set to the draft_updated_at you read. Validation issues come back on every save; errors only block publishing. Email content and its status (draft = skipped, manual = held for review, live = sent) are set per email step with PUT /flows/:id/messages/:nodeId and apply to the next sends without republishing.

Publishing takes two calls: the first returns the diff and a confirm_token (valid 10 minutes, for that exact draft), the second publishes with it. in_flight decides what happens to people already in the flow: keep them on their version, migrate them to the new one, or exit them. POST /flows/:id/simulate dry-runs a profile through the flow without sending anything. Reading needs read, editing and publishing full.

Publish in two steps
POST /api/v1/flows/FLOW_ID/publish   { "in_flight": "keep" }→ { "preview": { "diff": { "summary": ["Added email “Day 3 tips”"] }, … },    "confirm_token": "fc1…", "expires_at": "…" }POST /api/v1/flows/FLOW_ID/publish   { "confirm_token": "fc1…", "note": "Day 3 email" }→ { "version_id": "…", "version": 2, "in_flight": "keep" }

Flows triggered by an API call start with POST /flows/:id/runs (scope send): the profile is created or updated, data is available in the emails as {{ event.* }}, and the Idempotency-Key header is required, so a retry never starts the flow twice. The answer is 202; 409 means the flow isn't live or isn't an API flow.

Start a flow for one profile
curl https://app.rampsend.com/api/v1/flows/FLOW_ID/runs \  -H "Authorization: Bearer rs_live_…" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: trial-ada-2026-11" \  -d '{    "profile": { "email": "ada@example.com", "first_name": "Ada" },    "data": { "plan": "Pro", "trial_ends": "2026-12-04" }  }'

Idempotency

Add an Idempotency-Key header (any unique string, such as your order id) to make retries safe. Repeat the same request with the same key and you get the original response back, with an Idempotent-Replayed: true header — nothing is sent or charged twice. Reusing a key with a different body returns 422; a duplicate that arrives while the first is still running returns 409. Server errors (5xx) are not stored, so a retry runs again.

Header
Idempotency-Key: order-1042-receipt

Errors

Errors return JSON with a readable error message and a stable code to branch on.

403 Forbidden
{  "error": "Verify acme.eu under Deliverability → Domains before sending from it.",  "code": "domain_not_verified"}
StatusCodeWhen
400invalid_bodyThe body isn’t valid JSON.
401invalid_api_keyThe API key is missing, revoked or wrong.
402insufficient_creditsNot enough credit for the recipients in this call. Top up and retry.
403missing_scopeThe key doesn’t have the scope this endpoint needs (send or read).
403domain_not_verifiedThe from domain isn’t verified in this workspace yet.
403sending_pausedSending is paused for the workspace — see Deliverability in the app.
403workspace_suspendedThe workspace is on hold. Contact support.
404not_foundNo email with that id in this workspace.
409idempotency_conflictA request with the same Idempotency-Key is still running.
422validation_errorA field is missing or invalid. The message names the field.
422invalid_from / invalid_recipientAn address can’t be parsed, or a reserved header was set.
422idempotency_key_reusedThe Idempotency-Key was used before with a different body.
429rate_limitedToo many requests this minute. Wait for Retry-After.
429daily_limit_reachedNew accounts in review have a daily cap; it lifts once sending looks healthy.
500internal_errorSomething broke on our side. Safe to retry with the same Idempotency-Key.

Rate limits

Each API key has a per-minute request limit. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); a 429 adds Retry-After. Need more? Tell us.

MCP server

Rampsend speaks the Model Context Protocol, so Claude, ChatGPT, Cursor, VS Code, Claude Code and other MCP clients can send email, check stats and set up domains for you. Add the endpoint, sign in once in your browser (OAuth 2.1), and approve one workspace. Coding agents can send an API key in the Authorization header instead.

Streamable HTTP endpoint
https://app.rampsend.com/api/mcp
Claude Code
claude mcp add --transport http rampsend https://app.rampsend.com/api/mcp
Cursor · mcp.json
{  "mcpServers": {    "rampsend": { "url": "https://app.rampsend.com/api/mcp" }  }}

In Claude or ChatGPT, add a custom connector with the endpoint above. Connected assistants are listed under Integrations → AI assistants in the app, where you can revoke any of them.

Setup guides for each assistant →

ToolWhat it does
get_accountCredit balance, sending status, today’s sends and your domains.
send_emailSend from a verified domain (up to 50 recipients, 1 credit each). The assistant is asked to confirm with you first.
get_emailDelivery status and engagement for one email.
list_emailsRecent emails, filtered by status or recipient.
get_statsSent, delivered, bounces, complaints, opens, clicks and unsubscribes for the last N days — machine opens counted apart.
add_domainStart verifying a domain and get the DNS records to add.
check_domainRe-check a domain’s DNS and see what’s still missing.
upsert_contactCreate or update a contact, with custom properties.
find_contactsSearch contacts by email or name.
track_eventRecord something a person did (e.g. Placed Order) for segments and automations.
list_audiencesYour lists and segments with member counts.
add_to_listAdd people to a list by email or profile id.
list_flows · get_flowYour automations, and one automation’s steps, issues and results.
list_flow_templates · create_flowCreate an automation as a draft, from a template or a full document.
update_flow_draft · update_flow_emailEdit the steps, and write each email and set its status.
simulate_flowDry-run one profile through an automation without sending.
publish_flowPublish in two steps: the assistant shows you the diff and publishes only after you confirm.
set_flow_statusPause, resume or archive an automation.
enroll_in_flowStart an API-triggered automation for one profile.
list_flow_runs · get_flow_run · get_flow_reportWho is in an automation, one profile’s journey, and results by step.

Webhooks

Coming soon

Signed webhooks for delivery, bounce, complaint, open, click and unsubscribe events are coming soon. Until then, poll GET /api/v1/emails/:id or use the dashboard in the app.