SendForever help
Log in Get started

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:

  1. Open Settings in the team's navigation, then the API and MCP tab.
  2. In the API keys card, enter a name under New key, such as what will use it ("Claude Code").
  3. Choose the Access: Read only or Full access.
  4. Click Create key.
  5. 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_test sends 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 GET requests, send other inputs as query parameters, such as ?cursor=....
  • For POST, PUT and PATCH, send a JSON body with Content-Type: application/json.
  • A successful response is 200 with JSON whose data holds the result.
  • Errors are JSON with a message, and validation errors also list each field under errors.

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 as news.example.com.

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 as news.example.com.
  • host: the host to use, a name under the domain that nothing else uses. Left out, links. and the domain, such as links.news.example.com.

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 as news.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, as list_audiences gives 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 as news.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: the next_cursor of 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 or html, not both.
  • html: the whole email as HTML, as written elsewhere. Give this or markdown.
  • 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, as list_campaigns gives 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; name is 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 as 2026-11-03T09:00:00+00:00. If it has no offset, it is read in timezone.
  • timezone: the time zone to keep the schedule in, such as Europe/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).

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_host and remove_links_host publish 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_domains and send_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_campaign and remove_links_host are marked as changes that cannot be undone, so agents ask before using them.
  • The server tells agents to read a campaign with get_campaign before sending it, and to confirm send_campaign and stop_campaign with 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?

, which answers from these pages.

No page or section has those words.

Ask AI

ChatGPT or Claude answers in a new tab, from the SendForever docs. Only your question goes with it, nothing about your team.

Or read the help center

ChatGPT Claude