https://api.aigeon.ai/public/api/v1X-Api-Token header. Create a key under Settings → API Keys; each key carries the permissions an endpoint lists./manage/contacts/add-group-membersAdds up to 1000 contacts per request to one of your organization's List groups (send_group_id).
group_members: one object per contact, with its address and any properties.custom_fields: the names of the custom fields to set. Each is filled from the member property of the same name.organization_id and user_id in the body are ignored: the organization is always your API key's.Requires an API key with the contacts_access permission.
| Name | Type | Description |
|---|---|---|
group_membersrequired | array of object | Up to 1000 contacts. Each is an object with the contact's "email" plus any other properties to store on it, e.g. {"email": "reader@example.com", "first_name": "Ada"}. A contact whose email is missing or invalid is skipped and counted as invalid. |
send_group_idrequired | string | The List group to add the contacts to (from get-groups). |
custom_fields | array of string | Names of custom fields (string or number) to set from each contact's property of the same name. |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
attempted_email_cnt | integer | Number of members in the request. |
duplicated_email_cnt | integer | Members already in the group (or repeated in the request), so not added again. |
inserted_email_cnt | integer | Members added to the group. |
invalid_email_cnt | integer | Members skipped because their email address isn't valid. |
message | string | |
status | string |
curl -X POST 'https://api.aigeon.ai/public/api/v1/manage/contacts/add-group-members' \
-H 'X-Api-Token: <your API key>' \
-H 'Content-Type: application/json' \
-d '{
"group_members": [
{
"city": "Seattle",
"email": "reader@example.com",
"first_name": "Ada"
}
],
"send_group_id": "grp_xxxxxxxxxxxxxxxx",
"custom_fields": [
"city"
]
}'/manage/contacts/get-group-membersLists the members of one of your organization's groups, a List or a Segment, one page at a time. Each member has the same fields as a row of the console's Export Contacts.
Each member
email and hashed_email: the address, and the MD5 (hex) of the trimmed, lowercased address. Members added before 2026-01-22 may carry the MD5 of the address as it was added. When the address can't be read, email is empty (Export Contacts leaves such a member out). For a Segment this also happens for a contact deleted since the segment was last refreshed.added_at: when the member joined the group, in Unix seconds. Segment members have no join time, so for a Segment it's when the contact was created.status: deactivated if the contact unsubscribed from everything your organization sends, otherwise active.source, first_name, last_name, user_name, zipcode, hard_bounced, soft_bounced: from the contact's profile.custom_fields: your custom field values, by field name.Paging
after empty. After that, send the previous page's next_after.next_after is empty. The last page can itself be empty.limit is 1–1000 and defaults to 1000.members_count is counted fresh on every page.members_count is the count of that same set. A Segment that hasn't finished its first refresh has no members yet.Errors
| HTTP | code | when |
|---|---|---|
| 400 | 5000 | the group doesn't exist or isn't your organization's |
| 400 | 101 | a Segment: the version your first page read is no longer kept (Aigeon keeps the latest few); start again from the first page |
| 400 | 102 | the body isn't valid JSON, send_group_id is missing, after isn't a next_after value, or limit isn't a number from 1 to 1000 |
| 500 | -1 | temporary error; retry |
Requires an API key with the contacts_access permission.
| Name | Type | Description |
|---|---|---|
after | string | next_after from the previous page; empty for the first page. |
limit | integer | Members per page, 1–1000. Defaults to 1000. |
send_group_id | string | The group to read: a List or a Segment. |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
members | array of object | The members on this page, in member order. |
email | string | The member's address. Empty if it can't be decrypted. |
hashed_email | string | MD5 (hex) of the trimmed, lowercased address. Members added before 2026-01-22 may carry the MD5 of the address as it was added. |
added_at | integer | When the member joined the group (Unix seconds); the contact's creation time when the group doesn't record it. |
status | string | "deactivated" when the contact unsubscribed from everything the
organization sends, otherwise "active". One of: active, deactivated |
source | string | |
first_name | string | |
last_name | string | |
user_name | string | |
zipcode | string | |
hard_bounced | boolean | Mail to the address bounced permanently / temporarily. |
soft_bounced | boolean | |
custom_fields | object | The organization's custom field values, by field name. Fields with no value are left out. |
members_count | integer | The group's member count, counted when this page was read. |
next_after | string | Pass as "after" to get the next page; empty when this is the last one. |
organization_id | string | |
message | string | |
status | string |
curl -X POST 'https://api.aigeon.ai/public/api/v1/manage/contacts/get-group-members' \
-H 'X-Api-Token: <your API key>' \
-H 'Content-Type: application/json' \
-d '{
"after": "",
"limit": 1000,
"send_group_id": "grp_0123456789abcdef"
}'/manage/contacts/get-groupsLists your organization's groups, both List groups and Segments, so you can pick a send_group_id for /manage/campaign/create-and-schedule, /manage/contacts/add-group-members or /manage/contacts/get-group-members (the last two take List groups only).
Use type to get only one kind.
Requires an API key with the sending_access or contacts_access permission.
| Name | Type | Description |
|---|---|---|
typequery | string | Filter by group type: List or Segment. Omit for both. |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | array of object | |
create_time | integer | |
members_count | integer | |
send_group_id | string | |
send_group_name | string | |
type | string | |
update_time | integer | |
web_url | string | The group's page in the Aigeon console. |
message | string | |
status | string |
curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/contacts/get-groups' \ -H 'X-Api-Token: <your API key>'
/manage/contacts/refresh-segmentRe-runs a segment's membership query in the background and returns right away.
Nothing is started when
stale_hours.triggered in the response says whether this call started one.
Knowing when it's done: there is no callback. Call again later and watch segment_latest_available_version go up and segment_task_status become success.
Requires an API key with the sending_access or contacts_access permission.
| Name | Type | Description |
|---|---|---|
send_group_idrequired | string | The segment to refresh (a Segment group from get-groups). |
stale_hoursrequired | integer | If a successful refresh completed within this many hours, the request does nothing. At least 6. |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
last_refreshed_at | integer | When the segment's latest available version finished, as a UNIX timestamp in seconds. 0 when the segment has never finished a refresh, when its last refresh failed, or when reason is "already_running": then watch segment_latest_available_version instead. |
reason | string | "triggered" (a refresh started), "already_running" (one is in progress, so
none was started) or "recently_refreshed" (one finished within stale_hours,
so none was started). One of: triggered, already_running, recently_refreshed |
segment_latest_available_version | integer | |
segment_task_status | string | |
send_group_id | string | |
triggered | boolean | Whether this call started a new refresh. |
type | string | |
message | string | |
status | string |
curl -X POST 'https://api.aigeon.ai/public/api/v1/manage/contacts/refresh-segment' \
-H 'X-Api-Token: <your API key>' \
-H 'Content-Type: application/json' \
-d '{
"send_group_id": "grp_xxxxxxxxxxxxxxxx",
"stale_hours": 24
}'/manage/contacts/unsubscribeUnsubscribes up to 1000 contacts per request from everything your organization sends: every campaign and every flow.
Naming contacts (send one list, not both: HTTP 400 otherwise)
emails: email addresses, matched case-insensitively. Send these whenever you have them.hashed_emails: the MD5 (hex) of the trimmed, lowercased address, for contacts whose address you don't have. Each must match an existing contact: an unknown hash is reported in failed and nothing is recorded for it.What happens
unsubscribed.unsubscribed counts the address once.reason (optional) is stored with each opt-out: any text up to 128 characters, api_unsubscribe_all when not given. A bounce-like reason (bounce, hardbounce, MailboxFull, exceeding_whitelist_bounce_threshold, or an SMTP diagnostic such as smtp; 550 …) gets HTTP 400: Aigeon records bounces itself.
Failures: one failing entry doesn't stop the rest, so a response with code 0 can still have failures. Always check failed (in no particular order). Each entry names its email or hashed_email and has a kind:
| kind | meaning |
|---|---|
invalid_email, invalid_hashed_email | malformed; resending won't help |
unknown_hashed_email | no contact has this hash; send the address instead |
retryable | temporary error; resend it (unsubscribing again is harmless) |
Requires an API key with the contacts_access permission.
| Name | Type | Description |
|---|---|---|
emails | array of string | Email addresses. Send these whenever you have them. |
hashed_emails | array of string | MD5 of the trimmed, lowercased address, for contacts whose address you don't have. Each must match an existing contact. |
reason | string | Why the contacts unsubscribed, stored with the opt-out: up to 128 characters, not bounce-like. Optional; defaults to "api_unsubscribe_all". |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
failed | array of object | |
email | string | |
error | string | |
hashed_email | string | |
kind | string | One of: invalid_email, retryable, invalid_hashed_email, unknown_hashed_email |
unsubscribed | integer | |
message | string | |
status | string |
curl -X POST 'https://api.aigeon.ai/public/api/v1/manage/contacts/unsubscribe' \
-H 'X-Api-Token: <your API key>' \
-H 'Content-Type: application/json' \
-d '{
"emails": [
"reader@example.com",
"editor@example.com"
],
"hashed_emails": [
"5d41402abc4b2a76b9719d911017c592"
],
"reason": "crm_sync"
}'/manage/campaign/create-and-scheduleCreates a one-time campaign and schedules it.
The body has two parts that work together
content: what the email is, either a template_id or email_html.subject: where the subject line comes from. A "first_article" subject needs a template with an article block, because it reads the template's articles. With email_html, the subject must be "manual".A template_id is copied, not referenced. The send uses a private copy made when you call this, so later edits to your template don't change it. The copy keeps the template's article query, so the articles, and a "first_article" subject, are filled in at send time. The response returns both IDs: template_id is the one you sent, send_template_id is this send's copy.
Requires an API key with the sending_access permission.
| Name | Type | Description |
|---|---|---|
contentrequired | object | The email itself. Give exactly one of template_id and email_html. |
template_id | string | One of your organization's templates (from get-email-templates). Required for a "first_article" subject, and the template must then have an article block. |
email_html | string | A complete HTML email, which must contain an <html> tag. |
subjectrequired | object | The subject line and preheader. |
sourcerequired | string | Where the subject line comes from. "manual": text, as you wrote it.
"first_article": the title of the first article in the template, taken
when the campaign is sent, so it matches that day's articles. It needs a
template with an article block: a dynamic article block set to show at
least one row of articles, a static article block with at least one
article, or a custom article block. If the template has a custom article
block whose API response has a "subject" value, that value is the subject
instead. If the template's articles come back empty when the campaign is
sent, the send fails, so "first_article" never sends an email without
them. One of: manual, first_article |
textrequired | string | The subject line for "manual". For "first_article", it is used only when the first article has no title. |
preheader | string | Preview text shown after the subject in most inboxes. |
send_group_idrequired | string | The group to send to (from get-groups). |
sender_emailrequired | string | The full from-address. Its domain must be one of your organization's sending domains. |
display_namerequired | string | The sender name shown in the inbox. |
single_send_namerequired | string | The campaign's name in the console. |
send_time | integer | When to send, as a Unix timestamp in seconds. Omit it or send 0 to send now; a time more than a minute in the past is rejected. |
reply_to | string | The reply-to address. |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
campaign_id | string | ID of the campaign. |
flow_id | string | ID of the campaign's flow. Use it to read the campaign's stats (get-flow-stats). |
send_template_id | string | ID of the copy of the template this send uses. Later edits to your template don't change it. |
send_time | integer | Send time as a Unix timestamp in seconds. Only on success. |
status | string | Campaign status: "scheduled" on success, "draft" when scheduling failed. |
template_id | string | The template_id you sent, or, when you sent email_html, the ID of the template made from it. |
message | string | |
status | string |
curl -X POST 'https://api.aigeon.ai/public/api/v1/manage/campaign/create-and-schedule' \
-H 'X-Api-Token: <your API key>' \
-H 'Content-Type: application/json' \
-d '{
"content": {
"template_id": "tem_xxxxxxxxxxxxxxxx"
},
"subject": {
"source": "first_article",
"text": "This week'\''s top stories"
},
"send_group_id": "grp_xxxxxxxxxxxxxxxx",
"sender_email": "news@example.com",
"display_name": "Example News",
"single_send_name": "Weekly digest 2026-11-10",
"send_time": 1893456000,
"reply_to": "editor@example.com"
}'/manage/stats/get-org-statsDaily and total email statistics for your organization: sent, opens, clicks, unsubscribes, bounces, complaints and their rates.
start_date and end_date are inclusive and optional. Without them, every available day is returned.timezone, America/Los_Angeles by default.Requires an API key with the analytics_access permission.
| Name | Type | Description |
|---|---|---|
start_datequery | string | Start date (YYYY-MM-DD), inclusive |
end_datequery | string | End date (YYYY-MM-DD), inclusive |
timezonequery | string | Timezone the days are counted in (default America/Los_Angeles) One of: America/Los_Angeles, America/Denver, America/Chicago, America/New_York, UTC |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
daily_metrics | array of object | |
campaign_id | string | |
click_rate | number | |
complaint_rate | number | |
delivery_rate | number | |
email_bounce | integer | |
email_click | integer | |
email_complaint | integer | |
email_open | integer | |
email_sent | integer | |
email_softbounce | integer | |
email_start | integer | |
open_rate | number | |
pdate | string | |
total_clicks | integer | |
total_opens | integer | |
unsubscribe_all | integer | Unsubscribes from everything your organization sends; see unsubscribe_scoped. Left out for days before 2026-08-19. |
unsubscribe_rate | number | |
unsubscribe_scoped | integer | Unsubscribes from a single subscription. A reader can be counted here and in unsubscribe_all, so the two can add up to more than unsubscribe_total. Left out for days before 2026-08-19, which have no breakdown. |
unsubscribe_total | integer | Unsubscribes, by any route, from emails sent that day (counted on the send day, not the day of the unsubscribe). |
total_metrics | object | |
aggregated_total_clicks | integer | |
aggregated_total_opens | integer | |
bounce_rate | number | |
bounce_rate_grade | string | One of: fair, good |
click_rate | number | |
click_rate_grade | string | One of: fair, good |
complaint_rate | number | |
complaint_rate_grade | string | One of: fair, good |
delivery_rate | number | |
open_rate | number | |
open_rate_grade | string | One of: fair, good |
overall_score | integer | |
total_bounce | integer | |
total_click | integer | |
total_complaint | integer | |
total_open | integer | |
total_sent | integer | |
total_softbounce | integer | |
total_unsubscribe | integer | Unsubscribes, by any route, from emails sent in the range (counted on the day the email was sent, not the day of the unsubscribe). |
total_unsubscribe_all | integer | Unsubscribes from everything your organization sends; see total_unsubscribe_scoped. Counts only days from 2026-08-19 on, and is left out when the range has none. |
total_unsubscribe_scoped | integer | Unsubscribes from a single subscription. A reader can be counted here and in total_unsubscribe_all, so the two can add up to more than total_unsubscribe. Counts only days from 2026-08-19 on (earlier days have no breakdown), and is left out when the range has none. |
unsub_rate_grade | string | One of: fair, good |
unsubscribe_rate | number | |
message | string | |
status | string |
curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/stats/get-org-stats' \ -H 'X-Api-Token: <your API key>'
/manage/stats/get-flow-statsDaily email statistics for one of your organization's flows (flow_id).
Requires an API key with the analytics_access permission.
| Name | Type | Description |
|---|---|---|
flow_idrequiredquery | string | Flow ID |
start_datequery | string | Start date (YYYY-MM-DD) |
end_datequery | string | End date (YYYY-MM-DD) |
timezonequery | string | Timezone |
campaign_idquery | string | Campaign ID |
| Name | Type | Description |
|---|---|---|
code | integer | |
data | object | |
daily_metrics | array of object | |
campaign_id | string | |
click_rate | number | |
complaint_rate | number | |
delivery_rate | number | |
email_bounce | integer | |
email_click | integer | |
email_complaint | integer | |
email_open | integer | |
email_sent | integer | |
email_softbounce | integer | |
email_start | integer | |
open_rate | number | |
pdate | string | |
total_clicks | integer | |
total_opens | integer | |
unsubscribe_all | integer | Unsubscribes from everything your organization sends; see unsubscribe_scoped. Left out for days before 2026-08-19. |
unsubscribe_rate | number | |
unsubscribe_scoped | integer | Unsubscribes from a single subscription. A reader can be counted here and in unsubscribe_all, so the two can add up to more than unsubscribe_total. Left out for days before 2026-08-19, which have no breakdown. |
unsubscribe_total | integer | Unsubscribes, by any route, from emails sent that day (counted on the send day, not the day of the unsubscribe). |
total_metrics | object | |
aggregated_total_clicks | integer | |
aggregated_total_opens | integer | |
bounce_rate | number | |
bounce_rate_grade | string | One of: fair, good |
click_rate | number | |
click_rate_grade | string | One of: fair, good |
complaint_rate | number | |
complaint_rate_grade | string | One of: fair, good |
delivery_rate | number | |
open_rate | number | |
open_rate_grade | string | One of: fair, good |
overall_score | integer | |
total_bounce | integer | |
total_click | integer | |
total_complaint | integer | |
total_open | integer | |
total_sent | integer | |
total_softbounce | integer | |
total_unsubscribe | integer | Unsubscribes, by any route, from emails sent in the range (counted on the day the email was sent, not the day of the unsubscribe). |
total_unsubscribe_all | integer | Unsubscribes from everything your organization sends; see total_unsubscribe_scoped. Counts only days from 2026-08-19 on, and is left out when the range has none. |
total_unsubscribe_scoped | integer | Unsubscribes from a single subscription. A reader can be counted here and in total_unsubscribe_all, so the two can add up to more than total_unsubscribe. Counts only days from 2026-08-19 on (earlier days have no breakdown), and is left out when the range has none. |
unsub_rate_grade | string | One of: fair, good |
unsubscribe_rate | number | |
message | string | |
status | string |
curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/stats/get-flow-stats?flow_id=<flow_id>' \ -H 'X-Api-Token: <your API key>'
/manage/templates/get-email-templatesLists your organization's templates, so you can pick a template_id for /manage/campaign/create-and-schedule.
Per-send copies (the private copies that /manage/campaign/create-and-schedule and the web editor make for every send) are not listed.
Requires an API key with the sending_access permission.
| Name | Type | Description |
|---|---|---|
code | integer | |
data | array of object | |
create_time | integer | |
template_id | string | |
template_name | string | |
template_type | string | |
update_time | integer | |
web_url | string | The template's page in the Aigeon console. |
message | string | |
status | string |
curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/templates/get-email-templates' \ -H 'X-Api-Token: <your API key>'