Help Campaigns
Audiences and contacts
Audiences are the lists of people your campaigns go to, such as a weekly newsletter. The people in each audience are stored in a DynamoDB table in your own AWS account. This page covers how to create audiences, add people from your app, import, find and export contacts, read contact counts, use the page where people unsubscribe, and remove people and audiences.
How audiences work
Each audience belongs to one of your domains. To see a domain's audiences, choose the domain in the header and open Audiences. If you open an audience that belongs to another of your domains, SendForever switches the header to that domain. You can have any number of audiences.
- The audience itself (its name, the name people see and its description) is stored in SendForever, as a campaign is.
- The people in it are stored in the DynamoDB table
sendforever-contactsin your AWS account. SendForever reads the table when you open a page and copies no contacts into its own database. - Every subscription change goes through the same Step Functions workflow in your account, whether it comes from SendForever, from your app or from the page where people unsubscribe. Once someone leaves an audience, only they can put themselves back.
Contacts are kept per domain. The same address on two of your domains counts as two contacts. If the person unsubscribes from everything one domain sends, the other domain is not affected.
SendForever creates the table, with deletion protection and point-in-time recovery, when your AWS account is verified. This takes a minute. Until it is done, the page says Your contacts table is being made.
Team owners and admins can create and remove audiences, and add, import, unsubscribe and forget contacts. Members can see audiences and contacts, find a contact, export an audience and get the code for adding people from your app.
The links host
The unsubscribe link in every campaign email is served from the domain's links host, such as links.news.example.com. So is the API your app uses to add people. A domain on its own configuration set gets a links host at links. plus the domain when its first audience is made, unless that host already answers for something else. Until the links host is in use, the audiences page says so. Campaigns to the domain's audiences cannot be sent, and your app cannot call the API. See Domains to set one up.
The audiences list
The table shows each audience's Audience (the name people see), Name, Description, and how many people are Subscribed and Unsubscribed. Click a column heading to sort by it. Click a row to open the audience.
Create an audience
- Choose the domain in the header, then open Audiences.
- Click New audience.
- Fill in Name people see, for example "Weekly news". People see it when they unsubscribe, on the page where they choose what they receive.
- Check the Name. It copies the name people see until you type your own. Use up to 64 letters, numbers, dashes and underscores, like
weekly-news. Your app uses this name to subscribe people to the audience, so you cannot change it later. - Optionally, add a Description. It shows on the same page, below the name.
- Click Create audience.
The audience belongs to the domain that was chosen in the header when the page opened. It starts empty. People join when they subscribe or when you import them. You need a domain before you can create an audience (see Domains).
The audience page
The top of the page shows the name people see, the description and the audience's name, with a button to copy the name. Beside them, depending on your role, are Export CSV, Add from your app, Import CSV and Add contact.
The Subscribed tab lists who is in the audience, and the Unsubscribed tab lists who left it. Each tab shows how many people it has and the Last change to each contact. Click Load more for the next page. Click a person to see the emails the domain sent them in the Activity log.
Contact counts
- Counts are cached for up to 15 minutes. Pages show the last count right away while a new one runs. Changes you make in SendForever, and imports that finish, start a new count right away. People your app adds show in the list immediately and in the count within 15 minutes.
- Counting stops after the first pages of the table, which hold several tens of thousands of people. A count with a
+means at least that many. - Before a campaign is sent, its audience is always counted again, however recent the last count is.
Subscribers over time charts how many people were subscribed each day for the last 90 days. Your AWS account counts every audience in full once a day, around 04:00 UTC. An EventBridge Scheduler schedule starts a Step Functions state machine named sendforever-audience-counts, which reads the table and stores each audience's count as a CloudWatch metric (namespace SendForever, metric Subscribers, dimension Audience with the audience's ID). SendForever sets this up and runs the first count the first time someone opens an audience. The chart appears once there are two days of counts.
Find a contact
Type an address under Find someone by email and click Find. The answer says whether the person is in this audience, left it, unsubscribed from everything the domain sends, is a contact of the domain but not in this audience, or is not a contact of the domain. Owners and admins can click Forget this person under the answer, as in a person's row menu. This is the way to forget someone who is in none of the domain's audiences, such as after their audience was removed.
Add people from your app
SendForever has no signup form of its own. When someone signs up in your app, your app adds them to an audience through the subscriptions API on the domain's links host. Your campaigns to that audience then reach them. The API runs in your AWS account and nothing goes through SendForever's servers, so sign-ups keep working even while SendForever is down.
Your app calls the API with one of the domain's subscription keys. Click Add from your app on the Audiences page or on an audience's page to see the domain's keys and code in curl, Laravel, Node.js and Python. The code already has the domain's links host filled in, and on an audience's page, the audience's name too. A key works on every audience of that one domain. It can only add, remove and look up people there, and it cannot send email. For links.news.example.com and an audience named weekly-news:
curl https://links.news.example.com/api/v1/subscribe \
-H "Authorization: Bearer $SENDFOREVER_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "audience": "weekly-news"}'
- To make a key, a team owner or admin types a name for it, such as Production, and clicks Create key. A dialog shows the key once. Copy it and store it in your app's environment as
SENDFOREVER_KEY. SendForever keeps only a fingerprint of the key and writes that fingerprint to the contacts table in your AWS account, where the API looks keys up. - The list shows each of the domain's keys with its Name, the start and end of the Key, and when it was Created. Revoke removes a key from your account at once, and the next call with it is refused. Members see the list but not Create key or Revoke.
- The API runs on the domain's links host. Until the host is in use, Add from your app says so and links to the domain's configuration. Keys you make in the meantime start working once the host is in use.
Operations
Every operation is a POST to https://<links host>/api/v1/<operation>, with the key as a bearer token and a JSON object as the body.
| Operation | Body | Answers |
|---|---|---|
subscribe |
email, audience, optionally the person's name (up to 100 characters), and resubscribe: true for someone signing up again themselves |
status (subscribed or unchanged), email, audience, preferences_url and unsubscribe_url |
unsubscribe |
email, audience |
status (unsubscribed or unchanged), email, audience, preferences_url and unsubscribe_url |
contact |
email, and optionally the audience whose one-click link you want |
email, name (or null), audiences (each true or false), unsubscribed_from_all, preferences_url and unsubscribe_url |
upsert |
email, audience, and optionally name, subscribed, resubscribe, new_email and occurred_at |
status (subscribed, unsubscribed, updated, unchanged or ignored), email, audience, preferences_url and unsubscribe_url (see below) |
import |
audience, contacts (up to 500, each {"email", "name"}), and for an import that replaces the audience, replace, import_id and finish |
import_id, status and the counts added, updated, unchanged, skipped_left, invalid, left_out and removed (see below) |
unsubscribes |
audience, and optionally since (an ISO 8601 date and time) or the cursor of the next page |
audience, unsubscribes (each with email, source and unsubscribed_at) and next_cursor (see below) |
A name sent with subscribe becomes the person's name on the domain, and campaigns fill {{name}} with it. A call without a name leaves their name as it is. preferences_url is the person's page for choosing what they receive. unsubscribe_url is their one-click unsubscribe link for the audience. If your app sends bulk mail to the audience itself, first call contact for each person and skip anyone who is not in the audience or who unsubscribed from everything. Then put both links in the email (see Sending email). For a big list, send a campaign instead.
If someone left the audience or unsubscribed from everything the domain sends, your app can only add them back by sending resubscribe: true, which is for people who sign up again themselves. Without it, subscribe answers 409. For double opt-in, have your app ask people to confirm their address before it subscribes them.
Keep one person up to date
upsert updates one person on the domain in a single call. It is meant for an app that keeps its own record of who wants these emails:
curl https://links.news.example.com/api/v1/upsert \
-H "Authorization: Bearer $SENDFOREVER_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "audience": "weekly-news", "new_email": "[email protected]", "name": "Ana Silva", "occurred_at": "2026-11-10T09:30:00Z"}'
namechanges their name. Campaigns fill{{name}}with it.subscribed:trueadds them to the audience andfalseremoves them, assubscribeandunsubscribedo. Someone who left gets the same409, unlessresubscribe: truesays they are signing up again themselves. If you leavesubscribedout, their subscription stays as it is, and an address the domain does not have answers404.new_emailmoves them to another address. Every audience they joined or left, their name and their links move with them, and the links keep working. If the domain already has the new address, the call answers409withemail_taken, because two people are never merged. If the new address was forgotten after it left, the call answers409withemail_forgotten, because only that person's own sign-up brings the address back. If you send the same call again after the move went through, for example after a timeout, it finds them at the new address and continues there.occurred_atis when your app made the change, as an ISO 8601 date and time with its offset, such as2026-11-10T09:30:00Z. If it is earlier than the last change to the person, whatever made that change, the call changes nothing and answers"status": "ignored"withlast_changed_at. This way, calls that arrive out of order never undo a later one. Send one person's changes one at a time, waiting for each answer: two calls about the same person within a fraction of a second, one of them moving them to a new address, can leave the move undone in part. A time in the future counts as now.occurred_atonly puts your app's calls in order. The change itself is recorded when it arrives, and that is the time the webhook andunsubscribesreport.
The answer is the same as for subscribe. The status is updated when the name or address changed and the subscription did not. You can still use subscribe and unsubscribe on their own.
Import many people at once
import adds up to 500 people per call to an audience, as a CSV import does:
curl https://links.news.example.com/api/v1/import \
-H "Authorization: Bearer $SENDFOREVER_KEY" \
-H "Content-Type: application/json" \
-d '{"audience": "weekly-news", "contacts": [{"email": "[email protected]", "name": "Ana"}, {"email": "[email protected]"}]}'
The answer counts what happened to the people in the call: added to the audience, updated (already in it, with the new name you sent), unchanged, skipped_left (they left the audience or everything the domain sends, so only they can come back), invalid (no valid email) and left_out, which counts the newcomers left out as a CSV import leaves them out: trap (spam trap addresses), typo (misspelled domains, such as gmial.com), role (shared inboxes, such as info@) and disposable (throwaway inboxes). Someone already in the audience is kept whatever their address, so an import that replaces never takes them off for it. An import never brings back someone who left and never adds anyone twice, so it is safe to send the same people again, including after a 503. Send one call at a time per audience, and wait for each answer before you send the next. Calls sent together can go faster than your contacts table can write, and they answer 503. Addresses that Amazon SES suppressed after a bounce or complaint are imported too. Amazon SES never sends to them, and a campaign's report counts them under suppressed.
To make an audience match your own list and remove everyone who is not on it, import with replace:
- Send the first 500 with
"replace": true. The answer has"status": "open"and animport_id. - Send the rest, 500 per call, each with that
import_id. Leave outreplace, which would open another import. - Send
"finish": truewith theimport_id, on its own or with the last people. While the answer says"status": "finishing", send it again until it says"done". Each call removes up to 1,000 of the audience's members that the import did not list, counted inremoved, so a big audience takes a few calls.
finish only works with an import_id, so even a list of a few people takes two calls. A call that asks to finish without one answers 422 and removes nobody.
People the import removes are unsubscribed, by your app. Only subscribe or upsert with resubscribe: true brings them back, and later imports skip them. Anyone who joined, left or came back after the import started is left as they are. An import that listed nobody is refused when it finishes, so a mistake cannot empty an audience.
List who unsubscribed
unsubscribes lists the people who left an audience, oldest first, 500 per call. It is for an app that would rather ask once a day than receive the webhook's changes of subscription:
curl https://links.news.example.com/api/v1/unsubscribes \
-H "Authorization: Bearer $SENDFOREVER_KEY" \
-H "Content-Type: application/json" \
-d '{"audience": "weekly-news", "since": "2026-11-09T00:00:00Z"}'
Each person has their email, the source of the change as the webhook names it (email_link, one_click, preferences_page, dashboard or api), and unsubscribed_at. since leaves out people who left before that time. Without it, the list starts with the first person who ever left. While next_cursor is not null, send it back as cursor, with the same audience, to get the next page.
The list holds the people who are out of the audience now, with the last time they left and what took them off. Someone who left and came back is not in it. Unsubscribing someone who is already out changes neither, so an app that echoes a one-click back does not hide it. The first time someone in the team opens SendForever after this operation came out, your AWS account adds an index to the contacts table. This takes a few minutes, and until then the operation answers 409 with not_ready.
Errors and limits
An error answers with a status and {"error": {"code": ..., "message": ...}}:
| Status | Code | Why |
|---|---|---|
400 |
invalid_json |
The body is not a JSON object. |
401 |
unauthorized |
No key, a key SendForever did not make for this account, or a revoked key. |
404 |
not_found |
No such operation, or contact or upsert found nobody at the address. |
404 |
unknown_audience |
The domain has no audience by that name. |
404 |
unknown_import |
No import with that import_id replaces that audience of the domain. |
405 |
method_not_allowed |
The call is not a POST. |
409 |
left_audience, unsubscribed_from_all |
The person left; only resubscribe: true brings them back. |
409 |
email_taken |
upsert's new_email is an address the domain already has. |
409 |
email_forgotten |
upsert's new_email is an address that was forgotten after it left. |
409 |
import_closed |
People sent to an import that is finishing or finished. |
409 |
not_ready |
The list of unsubscribes is still being prepared in your AWS account. Try again in a few minutes. |
413 |
too_large |
The body is over 128 KB. |
422 |
invalid |
No valid email, or no audience to subscribe or unsubscribe; for import, no audience, contacts that are not a list of up to 500, or finish without an import_id; for unsubscribes, no audience, or a since or cursor that cannot be read; for upsert, a new_email, name, subscribed, resubscribe or occurred_at that cannot be read. |
422 |
too_many_audiences |
upsert's new_email for someone who joined or left more than 49 of the domain's audiences, which is more than one call can move. |
422 |
empty_list |
finish for an import that listed nobody, which would empty the audience. |
429 |
rate_limited |
The key made 600 calls this minute. Wait for the seconds in Retry-After, then try again. |
503 |
unavailable |
The API could not be reached just now. Try again in a little while. |
Each key can make up to 600 calls a minute. To add people you already have, import them 500 per call, or import a CSV from the audience page.
Add a contact by hand
Click Add contact, enter the Email and, optionally, the person's Name, then click Add contact. Campaigns fill {{name}} with the name. Only add people who asked to receive these emails. You cannot add back by hand someone who left the audience or unsubscribed from everything. Only they can subscribe again.
Import a CSV
An import adds people who are already on your list, for example an export from another newsletter tool. The file goes straight from your computer to your AWS account, which adds everyone in it to the audience.
- On the audience page, click Import CSV.
- Under CSV file, choose the file. SendForever reads it in your browser and checks it, as described below.
- Review what it found: how many addresses it will import, from which column, and what it left out.
- Check Everyone in this file asked to receive these emails.
- Click Import.
File format
Any CSV with a column of email addresses works. SendForever looks for a column headed email, e-mail, email address, subscriber email or address, then for any heading containing "email". A file without a heading row also works if its first row holds an address. Commas, semicolons and tabs all work as separators. For example:
email,name
[email protected],Ana
SendForever imports the addresses. It also imports each person's name if the file has a column headed name or full name, or else first name and last name columns, which it joins. It also reads a column that says who left the tool the file comes from (see below). All other columns are ignored. A name is kept on one line, without commas or double quotes, and up to 100 characters. If you import a file again, people already in the audience get the names the file has for them, and anyone the file has no name for keeps their name. Addresses are lowercased, and each one is imported once. A file can hold up to 1,000,000 addresses. Split a larger file and import each part.
Once the file is read, the Email, Name or first name and Last name menus show the columns SendForever chose. Choose others when the file names its columns its own way, for example Correio and Nome, or when it has more than one column of addresses, and SendForever reads the file again with them. Choose None to import no names. A file without a heading row has no columns to choose from: the addresses come from the column that holds them.
What is left out
Rows without a valid address are left out and counted. To protect your sending reputation, SendForever also leaves out the following, with a count and an example of each:
- people the file marks as unsubscribed, bounced or complained, so a list moved from another tool does not bring back anyone who left it there. This covers a
status(orsubscriber status,subscription status,subscriber type) such asunsubscribed,inactive,cancelled,bounced,cleanedorcomplained, a date they left (unsubscribed_at, Mailchimp'sUNSUB_TIMEandCLEAN_TIME), Ghost'ssubscribed_to_emailsatfalseor Substack'semail_disabledattrue. If the file lists someone more than once, they stay out if any of their rows marks them; - spam trap addresses, published on web pages to catch scrapers;
- misspelled domains, such as
gmial.comorgmail.con; - shared role addresses, such as
info@,support@orsales@; - throwaway inboxes, such as
mailinator.comaddresses; - addresses that bounced or complained before, which are on your account's Amazon SES suppression list and which Amazon SES would not send to anyway;
- addresses whose domain cannot receive email.
All of these checks run in your browser except the last one. For that one, SendForever's server looks up whether each domain in the file receives email, a hundred domains at a time. Only the domain names leave your computer. You can click Skip this check while it runs. If the suppression list cannot be read, the import says so and continues without that check.
Your AWS account also leaves out anyone who left this audience or unsubscribed from everything the domain sends, so an import never puts back people who chose to leave. It also leaves anyone already in the audience as they are. Importing the same file again adds nobody twice.
Consent
The import only starts once you confirm that everyone in the file asked to receive these emails. Bought, rented or scraped lists lead to spam complaints, and Amazon SES pauses accounts that get them.
SendForever keeps each import as the record of that confirmation. The Imports section of the audience page lists the latest five, with when each was Imported, the File name, who confirmed consent (Consent confirmed by), how many Contacts it had and how many were Left out. SendForever keeps these counts, not the addresses.
Following an import
The import runs in a Step Functions state machine named sendforever-contact-jobs in your account, a hundred addresses at a time. While it runs, the page shows Your AWS account is importing the file and how many contacts it has added so far. A million addresses take about an hour. You can close the page. The import keeps running, and whoever opens the audience next sees the result. When it ends, the page says how many contacts were added, how many were already in the audience, how many people in the file had unsubscribed and were left out, and how many rows were not email addresses. If your account stops the import, the page says why. Everyone the import reached is in the audience, so import the file again to add the rest.
The uploaded file is stored in your data bucket under audiences/imports/, and the stack expires it after seven days.
Export an audience
Click Export CSV to download a file named after the audience's name, like weekly-news.csv. It has two columns, email and status, and lists everyone subscribed and everyone who unsubscribed. Your browser writes the file, a thousand people at a time. An address that starts like a spreadsheet formula gets a leading ', so a spreadsheet does not run it. The button appears once someone is in the audience or has left it.
Unsubscribes
Every campaign email gets the person's own unsubscribe link, from the {{amazonSESUnsubscribeUrl}} in its template. It also gets the List-Unsubscribe and List-Unsubscribe-Post headers that Gmail and Yahoo use for one-click unsubscribe. Both are served from the domain's links host.
- One-click unsubscribe is the button a mailbox provider shows beside the sender. It removes the person from the campaign's audience at once.
- The link opens the domain's Email preferences page, which asks them to confirm that they want to leave the campaign's audience. The page shows their address partly hidden and lists every audience of the domain, with the name people see and its description. They can choose what they receive and click Save preferences, or Unsubscribe from everything the domain sends. The page shows only that domain's audiences, never another domain's.
- If they choose an audience again on the page, they are back in it, even after unsubscribing from everything, because it is their own choice.
The page runs in your AWS account, on the stack's function and a Step Functions workflow named sendforever-preferences. Opening the page never changes anything, so link scanners cannot unsubscribe anyone. When someone leaves the campaign's audience, the activity log records it, so the campaign's report counts it under Unsubscribed. Campaigns only go to the people subscribed to the audience. People who left appear on the Unsubscribed tab.
If the domain's webhook asks for changes of subscription, every unsubscribe and every person who comes back is posted to it, however it happened (see Webhook).
To remove someone yourself, open the menu on their row and choose Unsubscribe from this audience. See Templates for adding the unsubscribe link and Suppressions for addresses Amazon SES stops sending to after bounces and complaints.
Remove contacts and audiences
- Forget this person, in a person's row menu, deletes them from the domain: their contact and their place in every audience of the domain they are in or left. The links in emails already sent to them stop working. If they had never left anything, nothing about them is kept, and a later import or sign-up can add them again. If they had left an audience or everything the domain sends, only a SHA-256 fingerprint of their address stays, never the address. Then neither an import nor your app can add them back. They come back as having unsubscribed from everything, and only their own sign-up with
resubscribe: truebrings them back. Point-in-time recovery keeps deleted items restorable for up to 35 days, so after that a forgotten person is gone for good. - The trash button on an audience's row in the audiences list removes the audience, and campaigns can no longer be sent to it. SendForever refuses to remove it while a campaign to it is scheduled, sending or paused, or while a file is still being imported into it. The records of who is in it and who left it are then deleted from your contacts table in the background. The people themselves stay contacts of the domain, so someone who left everything stays out of later imports. To delete someone completely, find them and click Forget this person. For a big audience this takes a few minutes. The people stay among the domain's contacts, with their other audiences. If you want a copy, export the audience first. Point-in-time recovery keeps the deleted items restorable for up to 35 days. The record of the audience's imports is deleted with it, so keep your own proof of consent. A new audience with the same name starts empty.
Common questions
Why does a count end in +?
Counting stops after the first pages of the table, so a count that ends in + means the audience has at least that many people. The chart of Subscribers over time counts every audience in full once a day.
My app added people, but the count did not change. Why?
The list on the audience page is read live, but counts are cached for up to 15 minutes. The count catches up on its own.
Can I import names or other fields?
Names, yes. A name column, or first name and last name columns, is imported with the addresses, and campaigns fill {{name}} with it. Other fields are not imported, and campaigns fill only the {{email}} and {{name}} variables.
Why were addresses left out of my import?
The import leaves out invalid rows, people the file marks as unsubscribed, bounced or complained, spam traps, misspelled domains, role addresses, throwaway inboxes, suppressed addresses, domains that cannot receive email, and anyone who left the audience or unsubscribed from everything, even if you have forgotten them since. The import's summary gives a count and an example of each.
Can I add back someone who unsubscribed?
Not by hand or by import. Only they can subscribe again, either by choosing the audience on their preferences page or by signing up in your app again, which sends resubscribe: true.
Why don't I see Import CSV or Add contact?
Only team owners and admins can change audiences. Import CSV also needs the stack's data bucket. If it is missing, update the stack from the AWS account page.
Is there a signup form I can embed?
No. Your app adds subscribers through the subscriptions API on the domain's links host, with the code from Add from your app. If you want double opt-in, your app has to handle it.
How many audiences can I have?
As many as you like.
What happens to the people in an audience I remove?
Their membership of it, subscribed or unsubscribed, is deleted from your contacts table. They stay among the domain's contacts with their other audiences, and campaigns can no longer be sent to the audience.
Where are my contacts stored?
In the DynamoDB table sendforever-contacts in your own AWS account. Imported files go to your own S3 bucket and expire after seven days. SendForever stores no contacts. It keeps each audience's settings and last counts, and the record of each import: who confirmed consent, when, the file name and the counts.
Still stuck?