Help Team and account
API and MCP
SendForever has a REST API and an MCP server for AI agents. Both offer the same operations, and both authenticate with a team's API keys. This page covers creating and revoking keys, authentication, rate limits, errors, every operation and its parameters, what the API does not do, and how to connect an AI client to the MCP server.
Overview
A key lets your scripts and AI agents do what the team's pages do: read its domains, write templates, and create, send and track campaigns. Every operation is available in two ways:
- REST API at
https://app.sendforever.net/api/v1, one route per operation. - MCP server at
https://app.sendforever.net/mcp, one tool per operation, with the same name, inputs and behavior.
Both work on the team's own AWS account and use the same reads and checks as the pages. So an operation gives the same answer as the page that does the same thing.
API keys
Create a key
Team owners and admins can create keys:
- Open Settings in the team's navigation, then the API and MCP tab.
- In the API keys card, enter a name under New key, such as what will use it ("Claude Code").
- Choose the Access: Read only or Full access.
- Click Create key.
- Copy the key from the green box. It is shown only once. Click Done when you have copied it.
The same card lists the team's keys with Key (its name), Made by, Access and Last used. Members only see a note that owners and admins make and revoke keys. Below it, the Connecting card gives the addresses of the REST API, the OpenAPI description and the MCP server, plus the Claude Code command. Everything a key can do lists the operations below, grouped by what they work on: the AWS account, alerts, domains, audiences, contacts, templates and campaigns.
How a key maps to a team and a person
- A key belongs to one team. To work with several teams, make a key in each.
- A key acts as the person who made it, in that team only. For example,
send_campaign_testsends the test to that person's email address. - A key keeps working until it is revoked. Keys do not expire.
- A key stops working as soon as the person who made it is no longer in the team: they left, they were removed, or the team was deleted. If the maker deleted their account, the key shows A former member under Made by and no longer works.
- A key always acts on its own team, whatever team you have open in the browser. Using a key never switches the team open in the browser.
Read only and full access
- A Read only key can use only the operations that read.
- A Full access key can also use the operations that change something, but only while the person who made it is an owner or admin of the team. If that person becomes a member, the key can only read.
Members cannot create keys.
Revoke a key
Owners and admins can revoke any of the team's keys, no matter who made it. In the API keys card, click Revoke beside the key and confirm. Anything that uses the key stops working at once.
Authentication
Send the key as a bearer token in the Authorization header of every request:
Authorization: Bearer YOUR_KEY
A request without a key gets 401. Being signed in to SendForever in the browser does not authenticate API requests.
Base URL and versioning
The REST API is at https://app.sendforever.net/api/v1. The version is part of the path. Paths in this page are relative to that base URL, so GET /domains means GET https://app.sendforever.net/api/v1/domains.
An OpenAPI 3.1 description of every operation and its inputs is at https://app.sendforever.net/api/v1/openapi.json. Tools that generate API clients can use it. You do not need a key to read it.
Requests and responses
- Path parameters are part of the URL, such as the campaign id in
/campaigns/{campaign}. URL-encode values such as email addresses. - For
GETrequests, send other inputs as query parameters, such as?cursor=.... - For
POST,PUTandPATCH, send a JSON body withContent-Type: application/json. - A successful response is
200with JSON whosedataholds the result. - Errors are JSON with a
message, and validation errors also list each field undererrors.
For example, to list the team's domains:
curl https://app.sendforever.net/api/v1/domains \
-H "Authorization: Bearer YOUR_KEY" \
-H "Accept: application/json"
And to make a draft campaign:
curl -X POST https://app.sendforever.net/api/v1/campaigns \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"name": "October news", "template": "october-news", "audience": "weekly", "domain": "news.example.com", "from_local_part": "news"}'
Rate limits
Each key can make 120 requests a minute, across the REST API and the MCP server together. Every request to the MCP server counts, including the ones an agent makes to list the tools. Over the limit, requests get 429 until the minute is over.
send_campaign_test has its own limit: a domain can send up to 5 test emails an hour. It only sends a draft, as the campaign's page does, and answers 409 for any other campaign.
Errors
| Status | When |
|---|---|
401 |
No API key was sent, or it is not a valid key. |
403 |
The person who made the key is no longer in its team, or the operation changes something and the key can only read (or its maker is no longer an owner or admin). |
404 |
The domain, audience, contact, template or campaign named does not exist in the team or its AWS account. |
409 |
The team has no AWS account connected yet; the campaign or the domain's links host is not in a state that allows the operation (for example, the campaign is no longer a draft); a test or report is asked for before it can be made; or your Amazon SES account is in the sandbox and your address still needs verifying for send_campaign_test. |
422 |
An input is missing or invalid; the campaign's checks do not pass; a scheduled time is out of range; or AWS refused the request, and the message gives AWS's reason. |
429 |
The key's rate limit is used up. For send_campaign_test, also when the domain's hourly test emails are used up. |
503 |
AWS could not be reached, asked to be called less often, or could not complete the request. Try again in a little while. |
The message is meant to be shown as is to a person or an agent. For example: "This team has no AWS account connected yet. Connect one in SendForever first."
Operations
Each operation below lists its method and path, its MCP tool name, the access it needs, and its inputs. Inputs marked required must be sent. The others are optional. Operations that read work with any key. The others need Full access. Four operations cannot be undone: send_campaign, stop_campaign, delete_campaign and remove_links_host.
AWS account
Get the AWS account
GET /aws-account · get_aws_account · Read only
Shows how the team's AWS account is connected. The answer has its status (pending, connected, failed, disconnected, or not_connected for a team with none), its region, the stack_version it runs, the latest_stack_version and whether stack_is_current. stack_version is the version the stack last reported to SendForever. It is not read from AWS at request time, and it is null if the stack has not reported one.
Alerts
List alerts
GET /alerts · list_alerts · Read only
Lists the problems Amazon SES reported about the team's AWS account and domains that have not cleared yet, latest first. It is the same list the Alerts page shows under Needs attention. Each problem has its id, kind (bounce_rate, complaint_rate, sending_status or finding), domain (null for the whole account), title, detail and occurred_at. Problems the team ignored are not included. See Alerts and monitoring.
Domains
List domains
GET /domains · list_domains · Read only
Lists the team's sending domains, sorted by name. Each has its name, purpose (transactional or marketing), status, whether it is ready_to_send, whether sending_paused, whether it is isolated, and checked_at. Values come from each domain's last check. This call does not check the domains again.
Get a domain
GET /domains/{domain} · get_domain · Read only
Shows one sending domain: every check of its setup with what to do about it (checks), the DNS records it needs (records), the DNS changes still waiting to be published (waiting_dns_changes), and its links host (links_host, or null when it has none).
The domain's page reads the domain again when its last check is more than five minutes old, or seconds old while the domain waits for something. This call does the same, from Amazon SES and the DNS, so checked_at is recent. If the domain could not be read just now, the answer is the last check, and check_error says why. Each reading also takes a links host that is being set up or removed one step further.
links_host has the host, its status and an error when the setup failed. The status is certificate while Certificate Manager issues the certificate, distribution while CloudFront sets up the endpoint, dns while the host does not point at it yet, active once the host is in use, removing while it is taken down, and failed.
domain(required): the domain name, such asnews.example.com.
Set up a links host
POST /domains/{domain}/links-host · set_up_links_host · Full access
Starts setting up the domain's links host, as Use this host does on the domain's page. SendForever asks Certificate Manager for the certificate and then creates the CloudFront endpoint, both in the team's AWS account. This takes about half an hour, and it goes one step further each time get_domain reads the domain.
The host needs two DNS records on the way: one for the certificate, and later one that points the host at CloudFront. waiting_dns_changes lists each as it comes up. With a live Cloudflare authorization, the record known when you call this is published at once. A record that comes up later, and every record without that authorization, waits for a person to publish it, on the domain's page or with the DNS provider. See DNS records.
When the domain's last setup failed, this tries the same host again, or replaces it with the host you give. The answer is the domain, as get_domain gives it.
Answers 409 when the domain already has a links host or does not send through a configuration set of its own, and 422 when the host is not a name under the domain, is the domain's MAIL FROM, or has CAA records that do not allow Amazon.
domain(required): the domain name, such asnews.example.com.host: the host to use, a name under the domain that nothing else uses. Left out,links.and the domain, such aslinks.news.example.com.
Remove a links host
DELETE /domains/{domain}/links-host · remove_links_host · Full access · Cannot be undone
Stops using the domain's links host, as the Stop using button does on the domain's page. At once, its unsubscribe links and the subscriptions API stop answering there, and opens and clicks are tracked on Amazon's domain again. The CloudFront endpoint and the certificate are then deleted from the team's AWS account over a few minutes, one step further each time get_domain reads the domain. The host's own DNS record has to go too, or the same host cannot be set up again: with a live Cloudflare authorization it is removed at once, and otherwise waiting_dns_changes lists it with change set to remove, for a person to delete. Setting a host up again takes about half an hour and new DNS records.
Answers 409 while a campaign's unsubscribe links still need the host (a campaign scheduled or sending, or one sent in the last 30 days), when the host is already being taken down, and when the domain has none. The answer is the domain, as get_domain gives it.
domain(required): the domain name, such asnews.example.com.
Audiences and contacts
List audiences
GET /audiences · list_audiences · Read only
Lists the team's audiences, each with its name, display_name, description and the domain whose campaigns go to it. A campaign goes to one audience.
Get an audience
GET /audiences/{audience} · get_audience · Read only
Shows one audience and how many people are subscribed to it. SendForever counts them in the contacts table of the team's AWS account. subscribed is the count. For a very large audience, only the first few tens of thousands are counted, and subscribed_more is true.
audience(required): the audience's name, aslist_audiencesgives it.
Find a contact
GET /contacts/{email} · find_contact · Read only
Looks up one email address among the contacts of one of the team's domains. The answer has the contact's name (or null), the domain's audiences the address is subscribed to or left (audiences, each true or false), and whether it unsubscribed from everything the domain sends (unsubscribed_from_all). Answers 404 when the domain has no contact at that address.
email(required): the email address to look up.domain(required): the domain whose contacts to look in, such asnews.example.com.
This API reads contacts but does not add them. Your app adds people through the subscriptions API on each domain's links host, using one of the domain's subscription keys. See Audiences and contacts.
Templates
List templates
GET /templates · list_templates · Read only
Lists the email templates in Amazon SES, fifty at a time, each with its name and created_at. When there are more, next_cursor is set. Pass it as cursor to get the next page.
cursor: thenext_cursorof the previous page.
Get a template
GET /templates/{template} · get_template · Read only
Shows one email template as Amazon SES has it: subject, html, text, its preview_text, the variables it uses, and how it was written (written_in: visual, markdown or html).
template(required): the template's name in Amazon SES.
Save a template
PUT /templates/{template} · save_template · Full access
Creates an email template in Amazon SES from Markdown or HTML, or replaces the template with that name. Markdown gets the same layout as the visual editor and is kept as the text version. Every campaign email needs the unsubscribe link, so write {{amazonSESUnsubscribeUrl}} as a link's address. The answer says whether the template was created (true) or replaced (false). If a scheduled or sending campaign uses the template, saving it answers 409 until that campaign ends or is cancelled.
template(required): the template's name, up to 64 letters, numbers, dashes and underscores.subject(required): the subject line, up to 255 characters.{{email}}and{{name}}are filled in for each person.markdown: the email in Markdown. Give this orhtml, not both.html: the whole email as HTML, as written elsewhere. Give this ormarkdown.text: the text version for HTML. If you leave it out, it is made from the HTML.preview_text: for Markdown, the text inboxes show beside the subject, up to 255 characters.
See Templates for how templates and their variables work.
Campaigns
A campaign is returned with its id, name, status (draft, scheduled, sending, paused, sent, stopped or failed), template, audience, domain, from, reply_to, pace_per_hour, scheduled_at, started_at, finished_at and error. Use the id wherever an operation asks for campaign.
Campaign settings
create_campaign and update_campaign take these settings:
| Setting | What it is |
|---|---|
name |
The campaign's name in SendForever, up to 255 characters. Required when creating. |
template |
The name of the Amazon SES template it sends. |
audience |
The name of the audience it goes to. |
domain |
The sending domain it goes out from, such as news.example.com. It must be one of the team's domains. |
from_name |
The sender name people see, up to 100 characters. A new campaign starts with its domain's sender name. |
from_local_part |
The part of the from address before the @, such as news. It can use letters, digits, dots, underscores, plus signs and dashes. If left out, newsletter. |
reply_to |
Where replies go. If left out, replies go to the from address. |
pace_per_hour |
The most emails to send in an hour, to warm up a new domain: 500, 1000, 2500, 5000 or 10000. If left out, the campaign sends as fast as the account allows. |
List campaigns
GET /campaigns · list_campaigns · Read only
Lists the team's campaigns, newest first (up to 100), with the status SendForever last saw. To read a campaign's current status from AWS, use get_campaign.
Get a campaign
GET /campaigns/{campaign} · get_campaign · Read only
Shows one campaign, with its status read fresh from AWS. For a draft, checks lists the checks that must pass before it can be sent, each with a key, status and message. While it is sending, progress says how far it got. If it stopped or failed, error says why.
campaign(required): the campaign's id, aslist_campaignsgives it.
Only checks with the status fail stop a campaign from being sent. Warnings are worth reading but do not block it. See Campaigns for what each check means.
Create a campaign
POST /campaigns · create_campaign · Full access
Creates a draft campaign: the template it sends, the audience it goes to, the domain it goes out from, and its pace. Nothing is sent until you call send_campaign or schedule_campaign.
- The campaign settings above;
nameis required.
Update a campaign
PATCH /campaigns/{campaign} · update_campaign · Full access
Changes a draft campaign's settings. Only the settings you send change. You cannot change a campaign that has started.
campaign(required): the campaign's id.- Any of the campaign settings above.
Duplicate a campaign
POST /campaigns/{campaign}/duplicate · duplicate_campaign · Full access
Creates a new draft with a campaign's settings (template, audience, domain, from, reply-to and pace) and returns it. The copy has the original's name with "(copy)" at the end. Nothing from the original's sending carries over, so you test, send or schedule the copy on its own. You can duplicate any campaign, whatever its status.
campaign(required): the id of the campaign to copy.
Send a test
POST /campaigns/{campaign}/test · send_campaign_test · Full access
Sends a draft campaign's email once to the person who made the API key, from the campaign's address and with its reply-to. {{email}} is filled with that person's address and {{name}} with their name. The unsubscribe link opens a page that says the email is a test, and it changes nothing. The campaign needs its domain and a template that exists in Amazon SES. The answer gives the address it was sent to in sent_to.
campaign(required): the campaign's id.
Send a campaign
POST /campaigns/{campaign}/send · send_campaign · Full access · Cannot be undone
Sends a draft campaign now to everyone in its audience, from the team's AWS account. It only starts if every check that get_campaign lists passes. Otherwise it answers 422 with the checks that fail.
campaign(required): the campaign's id.
Schedule a campaign
POST /campaigns/{campaign}/schedule · schedule_campaign · Full access
Schedules a draft campaign for the team's AWS account to send at a set time, between five minutes and a year from now. It only schedules if every check that get_campaign lists passes. cancel_schedule undoes it.
campaign(required): the campaign's id.send_at(required): when to send, as an ISO 8601 date and time, such as2026-11-03T09:00:00+00:00. If it has no offset, it is read intimezone.timezone: the time zone to keep the schedule in, such asEurope/Lisbon. If left out, UTC.
Cancel a schedule
POST /campaigns/{campaign}/unschedule · cancel_schedule · Full access
Turns a scheduled campaign back into a draft, before it starts.
campaign(required): the campaign's id.
Pause a campaign
POST /campaigns/{campaign}/pause · pause_campaign · Full access
Pauses a campaign that is sending. It stops between two pages of its audience, after the emails already handed to Amazon SES go out. Within 14 days, resume_campaign continues it from there without sending to anyone twice. A campaign that is not sending answers 409.
campaign(required): the campaign's id.
Resume a campaign
POST /campaigns/{campaign}/resume · resume_campaign · Full access
Continues a paused campaign from where it stopped, or a failed one from where it failed, within 14 days. It returns the campaign, now sending. People it already reached do not get the email twice. A campaign that stopped because of its bounces or complaints, or one past the 14 days, answers 409.
campaign(required): the campaign's id.
Stop a campaign
POST /campaigns/{campaign}/stop · stop_campaign · Full access · Cannot be undone
Stops a campaign that is sending or paused, permanently. Emails already sent stay sent, and the campaign cannot be resumed.
campaign(required): the campaign's id.
Delete a campaign
DELETE /campaigns/{campaign} · delete_campaign · Full access · Cannot be undone
Deletes a campaign that is not scheduled or sending. A scheduled campaign answers 409 until you call cancel_schedule. A sending one answers 409 until you call stop_campaign or it ends. Its emails and their events stay in the team's AWS account. The answer is the deleted campaign's id, with deleted set to true.
campaign(required): the campaign's id.
Campaign report
GET /campaigns/{campaign}/report · campaign_report · Read only
Shows what happened to a campaign's emails, from the activity log in the team's AWS account: sent, delivered, opened, clicked, bounced, suppressed, complained and unsubscribed. Each is given in total and per mailbox provider (providers). read_at says when the log was read. Read the report again no more than once every few minutes. A campaign that has not started has nothing to report.
campaign(required): the campaign's id.
The report reads the activity log, so the activity log must be set up in the team's AWS account (see Activity).
Campaign links
GET /campaigns/{campaign}/links · campaign_links · Read only
Lists the links people clicked in a campaign's emails (links), most clicked first, up to 50. Each has its link and clicked, the number of emails it was clicked in. An email counts once, however many times the link was clicked in it. read_at says when the log was read. Like the report, this reads the activity log, so read it no more than once every few minutes. A campaign that has not started answers 409.
campaign(required): the campaign's id.
What the API does not do
The operations above are everything a key can do. In particular, the API and the MCP server do not:
- Add, change or remove contacts or their subscriptions. Your own app does that through the subscriptions API on each domain's links host, using one of the domain's subscription keys. The audience pages also add people by hand or from a CSV (see Audiences and contacts).
- Send individual emails. Your app sends through Amazon SES directly, with the domain's sending credentials (see Sending). A SendForever API key is not an AWS key and cannot send email.
- Add or remove domains, connect the AWS account, or change a domain's settings other than its links host.
- Publish DNS records on request. Only
set_up_links_hostandremove_links_hostpublish or remove one, as described above. - Create or delete audiences, or delete templates.
- Manage sending credentials, subscription keys, suppressions, the webhook, the activity log, members or API keys, or ignore alerts.
Use the team's pages for those.
MCP server
The MCP server at https://app.sendforever.net/mcp offers every operation as a tool, with the same names, inputs and limits as the REST API. It uses the same API keys.
Connect Claude Code
Right after you create a key, the Connecting card shows this command with the key already filled in. The server name includes your team's name, so you can add several teams side by side:
claude mcp add --transport http sendforever-your-team https://app.sendforever.net/mcp --header 'Authorization: Bearer YOUR_KEY'
Other AI clients
The server is a remote MCP server over HTTP. It only accepts an API key sent in the Authorization: Bearer YOUR_KEY header, and it has no OAuth sign-in. Any MCP client that can add a remote HTTP server with a custom header can connect. Give it the server URL and that header. A client that can only connect to remote servers through OAuth cannot use it.
What agents see
- The tools are named like the operations above, such as
list_domainsandsend_campaign. - A key with Read only access is offered only the tools that read.
- Each tool says whether it only reads.
send_campaign,stop_campaign,delete_campaignandremove_links_hostare marked as changes that cannot be undone, so agents ask before using them. - The server tells agents to read a campaign with
get_campaignbefore sending it, and to confirmsend_campaignandstop_campaignwith you first. It also tells them that your own app adds contacts, through the subscriptions API on each domain's links host. - An operation that fails comes back as a tool error with the same message the REST API gives.
Common questions
Where do I find my API key again?
You cannot. A key is shown only once, when you create it. If you lost it, revoke it and create a new one.
Why do I get 403 when I create a campaign?
Either the key is Read only, or the person who made it is no longer an owner or admin of the team. Make a key with Full access as an owner or admin. A 403 also comes back for every request when the key's maker has left the team.
Why do I get 409 "This team has no AWS account connected yet"?
Most operations read the team's AWS account. Connect it first (see AWS account). Only get_aws_account, list_domains, get_domain, list_audiences, list_campaigns, create_campaign and update_campaign work without it.
Why does send_campaign answer 422?
At least one of the campaign's checks fails. The message lists what to fix, and get_campaign shows every check. A common one is an Amazon SES account still in the sandbox (see Production access).
Can one key work for several teams?
No. A key belongs to the team it was made in. Make a key in each team.
Can I add contacts or subscribe people through the API?
No. Your own app subscribes and unsubscribes people through the subscriptions API on the domain's links host. It uses one of the domain's subscription keys, not a SendForever API key. The subscriptions API runs in your AWS account, so sign-ups keep working even when SendForever is down. See Add people from your app. To look up one address, use find_contact.
Can I send a transactional email through the API?
No. SendForever never sends your email for you. Send through Amazon SES with the domain's SMTP or API credentials (see Sending).
Does the MCP server count against the same limit?
Yes. The 120 requests a minute are per key, across the REST API and the MCP server together.
Can I connect the MCP server to a client that only supports OAuth?
No. The server only accepts an API key in the Authorization header. Use a client that lets you set that header, such as Claude Code with the command above.
Still stuck?