Aigeon Public API

Base URL: https://api.aigeon.ai/public/api/v1
Authentication: send your organization's API key in the X-Api-Token header. Create a key under Settings → API Keys; each key carries the permissions an endpoint lists.

Contacts

Add contacts to a group

post/manage/contacts/add-group-members

Adds 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.

Request bodyapplication/json

NameTypeDescription
group_membersrequiredarray of objectUp 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_idrequiredstringThe List group to add the contacts to (from get-groups).
custom_fieldsarray of stringNames of custom fields (string or number) to set from each contact's property of the same name.

Response (200)

NameTypeDescription
codeinteger
dataobject
attempted_email_cntintegerNumber of members in the request.
duplicated_email_cntintegerMembers already in the group (or repeated in the request), so not added again.
inserted_email_cntintegerMembers added to the group.
invalid_email_cntintegerMembers skipped because their email address isn't valid.
messagestring
statusstring

Example

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"
  ]
}'

List the members of a group

post/manage/contacts/get-group-members

Lists 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

  • First page: send after empty. After that, send the previous page's next_after.
  • Stop when next_after is empty. The last page can itself be empty.
  • limit is 1–1000 and defaults to 1000.
  • List: members come in roughly the order they were added. A member added while you page usually shows up at the end, but can be missed until your next pass. Removed members are not returned. members_count is counted fresh on every page.
  • Segment: you page through the members as of your first page. A refresh while you page doesn't change the pages you get; start again from the first page to read the refreshed members. members_count is the count of that same set. A Segment that hasn't finished its first refresh has no members yet.

Errors

HTTPcodewhen
4005000the group doesn't exist or isn't your organization's
400101a Segment: the version your first page read is no longer kept (Aigeon keeps the latest few); start again from the first page
400102the 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-1temporary error; retry

Requires an API key with the contacts_access permission.

Request bodyapplication/json

NameTypeDescription
afterstringnext_after from the previous page; empty for the first page.
limitintegerMembers per page, 1–1000. Defaults to 1000.
send_group_idstringThe group to read: a List or a Segment.

Response (200)

NameTypeDescription
codeinteger
dataobject
membersarray of objectThe members on this page, in member order.
emailstringThe member's address. Empty if it can't be decrypted.
hashed_emailstringMD5 (hex) of the trimmed, lowercased address. Members added before 2026-01-22 may carry the MD5 of the address as it was added.
added_atintegerWhen the member joined the group (Unix seconds); the contact's creation time when the group doesn't record it.
statusstring"deactivated" when the contact unsubscribed from everything the organization sends, otherwise "active".
One of: active, deactivated
sourcestring
first_namestring
last_namestring
user_namestring
zipcodestring
hard_bouncedbooleanMail to the address bounced permanently / temporarily.
soft_bouncedboolean
custom_fieldsobjectThe organization's custom field values, by field name. Fields with no value are left out.
members_countintegerThe group's member count, counted when this page was read.
next_afterstringPass as "after" to get the next page; empty when this is the last one.
organization_idstring
messagestring
statusstring

Example

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"
}'

List groups

get/manage/contacts/get-groups

Lists 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.

Parameters

NameTypeDescription
type
query
stringFilter by group type: List or Segment. Omit for both.

Response (200)

NameTypeDescription
codeinteger
dataarray of object
create_timeinteger
members_countinteger
send_group_idstring
send_group_namestring
typestring
update_timeinteger
web_urlstringThe group's page in the Aigeon console.
messagestring
statusstring

Example

curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/contacts/get-groups' \
  -H 'X-Api-Token: <your API key>'

Refresh a segment

post/manage/contacts/refresh-segment

Re-runs a segment's membership query in the background and returns right away.

Nothing is started when

  • a refresh is already running, or
  • a refresh succeeded within the last 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.

Request bodyapplication/json

NameTypeDescription
send_group_idrequiredstringThe segment to refresh (a Segment group from get-groups).
stale_hoursrequiredintegerIf a successful refresh completed within this many hours, the request does nothing. At least 6.

Response (200)

NameTypeDescription
codeinteger
dataobject
last_refreshed_atintegerWhen 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.
reasonstring"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_versioninteger
segment_task_statusstring
send_group_idstring
triggeredbooleanWhether this call started a new refresh.
typestring
messagestring
statusstring

Example

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
}'

Unsubscribe contacts from your organization

post/manage/contacts/unsubscribe

Unsubscribes 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

  • An address that isn't a contact yet is recorded as unsubscribed, so adding it later keeps it unsubscribed.
  • A contact that is already unsubscribed is left as it is and still counted in unsubscribed.
  • Every spelling of an address you send is unsubscribed, and 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:

kindmeaning
invalid_email, invalid_hashed_emailmalformed; resending won't help
unknown_hashed_emailno contact has this hash; send the address instead
retryabletemporary error; resend it (unsubscribing again is harmless)

Requires an API key with the contacts_access permission.

Request bodyapplication/json

NameTypeDescription
emailsarray of stringEmail addresses. Send these whenever you have them.
hashed_emailsarray of stringMD5 of the trimmed, lowercased address, for contacts whose address you don't have. Each must match an existing contact.
reasonstringWhy the contacts unsubscribed, stored with the opt-out: up to 128 characters, not bounce-like. Optional; defaults to "api_unsubscribe_all".

Response (200)

NameTypeDescription
codeinteger
dataobject
failedarray of object
emailstring
errorstring
hashed_emailstring
kindstring
One of: invalid_email, retryable, invalid_hashed_email, unknown_hashed_email
unsubscribedinteger
messagestring
statusstring

Example

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"
}'

Campaign

Create and schedule a one-time campaign

post/manage/campaign/create-and-schedule

Creates 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.

Request bodyapplication/json

NameTypeDescription
contentrequiredobjectThe email itself. Give exactly one of template_id and email_html.
template_idstringOne 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_htmlstringA complete HTML email, which must contain an <html> tag.
subjectrequiredobjectThe subject line and preheader.
sourcerequiredstringWhere 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
textrequiredstringThe subject line for "manual". For "first_article", it is used only when the first article has no title.
preheaderstringPreview text shown after the subject in most inboxes.
send_group_idrequiredstringThe group to send to (from get-groups).
sender_emailrequiredstringThe full from-address. Its domain must be one of your organization's sending domains.
display_namerequiredstringThe sender name shown in the inbox.
single_send_namerequiredstringThe campaign's name in the console.
send_timeintegerWhen 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_tostringThe reply-to address.

Response (200)

NameTypeDescription
codeinteger
dataobject
campaign_idstringID of the campaign.
flow_idstringID of the campaign's flow. Use it to read the campaign's stats (get-flow-stats).
send_template_idstringID of the copy of the template this send uses. Later edits to your template don't change it.
send_timeintegerSend time as a Unix timestamp in seconds. Only on success.
statusstringCampaign status: "scheduled" on success, "draft" when scheduling failed.
template_idstringThe template_id you sent, or, when you sent email_html, the ID of the template made from it.
messagestring
statusstring

Example

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"
}'

Stats

Get your organization's stats

get/manage/stats/get-org-stats

Daily 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.
  • Days are counted in timezone, America/Los_Angeles by default.

Requires an API key with the analytics_access permission.

Parameters

NameTypeDescription
start_date
query
stringStart date (YYYY-MM-DD), inclusive
end_date
query
stringEnd date (YYYY-MM-DD), inclusive
timezone
query
stringTimezone the days are counted in (default America/Los_Angeles)
One of: America/Los_Angeles, America/Denver, America/Chicago, America/New_York, UTC

Response (200)

NameTypeDescription
codeinteger
dataobject
daily_metricsarray of object
campaign_idstring
click_ratenumber
complaint_ratenumber
delivery_ratenumber
email_bounceinteger
email_clickinteger
email_complaintinteger
email_openinteger
email_sentinteger
email_softbounceinteger
email_startinteger
open_ratenumber
pdatestring
total_clicksinteger
total_opensinteger
unsubscribe_allintegerUnsubscribes from everything your organization sends; see unsubscribe_scoped. Left out for days before 2026-08-19.
unsubscribe_ratenumber
unsubscribe_scopedintegerUnsubscribes 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_totalintegerUnsubscribes, by any route, from emails sent that day (counted on the send day, not the day of the unsubscribe).
total_metricsobject
aggregated_total_clicksinteger
aggregated_total_opensinteger
bounce_ratenumber
bounce_rate_gradestring
One of: fair, good
click_ratenumber
click_rate_gradestring
One of: fair, good
complaint_ratenumber
complaint_rate_gradestring
One of: fair, good
delivery_ratenumber
open_ratenumber
open_rate_gradestring
One of: fair, good
overall_scoreinteger
total_bounceinteger
total_clickinteger
total_complaintinteger
total_openinteger
total_sentinteger
total_softbounceinteger
total_unsubscribeintegerUnsubscribes, 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_allintegerUnsubscribes 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_scopedintegerUnsubscribes 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_gradestring
One of: fair, good
unsubscribe_ratenumber
messagestring
statusstring

Example

curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/stats/get-org-stats' \
  -H 'X-Api-Token: <your API key>'

Get flow stats

get/manage/stats/get-flow-stats

Daily email statistics for one of your organization's flows (flow_id).

  • A flow of another organization returns "flow not found".

Requires an API key with the analytics_access permission.

Parameters

NameTypeDescription
flow_idrequired
query
stringFlow ID
start_date
query
stringStart date (YYYY-MM-DD)
end_date
query
stringEnd date (YYYY-MM-DD)
timezone
query
stringTimezone
campaign_id
query
stringCampaign ID

Response (200)

NameTypeDescription
codeinteger
dataobject
daily_metricsarray of object
campaign_idstring
click_ratenumber
complaint_ratenumber
delivery_ratenumber
email_bounceinteger
email_clickinteger
email_complaintinteger
email_openinteger
email_sentinteger
email_softbounceinteger
email_startinteger
open_ratenumber
pdatestring
total_clicksinteger
total_opensinteger
unsubscribe_allintegerUnsubscribes from everything your organization sends; see unsubscribe_scoped. Left out for days before 2026-08-19.
unsubscribe_ratenumber
unsubscribe_scopedintegerUnsubscribes 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_totalintegerUnsubscribes, by any route, from emails sent that day (counted on the send day, not the day of the unsubscribe).
total_metricsobject
aggregated_total_clicksinteger
aggregated_total_opensinteger
bounce_ratenumber
bounce_rate_gradestring
One of: fair, good
click_ratenumber
click_rate_gradestring
One of: fair, good
complaint_ratenumber
complaint_rate_gradestring
One of: fair, good
delivery_ratenumber
open_ratenumber
open_rate_gradestring
One of: fair, good
overall_scoreinteger
total_bounceinteger
total_clickinteger
total_complaintinteger
total_openinteger
total_sentinteger
total_softbounceinteger
total_unsubscribeintegerUnsubscribes, 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_allintegerUnsubscribes 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_scopedintegerUnsubscribes 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_gradestring
One of: fair, good
unsubscribe_ratenumber
messagestring
statusstring

Example

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>'

Templates

List templates

get/manage/templates/get-email-templates

Lists 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.

Response (200)

NameTypeDescription
codeinteger
dataarray of object
create_timeinteger
template_idstring
template_namestring
template_typestring
update_timeinteger
web_urlstringThe template's page in the Aigeon console.
messagestring
statusstring

Example

curl -X GET 'https://api.aigeon.ai/public/api/v1/manage/templates/get-email-templates' \
  -H 'X-Api-Token: <your API key>'
Ready to transform the way you send?
Share your details and our team will be in touch to schedule a personalized live demo.

Modernize Your Email Strategy.

We'll be in touch shortly to help you get started.
© Aigeon.ai 2025
All Rights Reserved