Notification Contacts

Introduction

Notification contacts are the email addresses where Avenia sends notices about your account: integration changes, compliance requests, fees, scheduled maintenance and so on. Each address takes one or more categories, so each team receives the notices meant for it.

The same list is managed in the Avenia dashboard, under Settings. What you change through the API shows up there, and the other way round.

info

Contacts belong to the Main Account. Its subAccounts share them, and these endpoints ignore subAccountId. Every login can list the contacts; only an admin login (or an API key of one) can add, change or remove them, or resend a link.

Categories

Category	Notices about
tech	Integration, API and technical changes.
compliance	KYC, KYB and compliance requests.
finance	Fees, balances and financial notices.
general	General notices, and any category nobody is set for.
commercial	Pricing, products and commercial updates.
operations	Scheduled maintenance and service disruptions.

• An address with no category goes to general.
• A category takes up to 10 addresses. The same address can be in several categories, and receives a single copy of a notice sent to more than one of them.
• When a notice goes to a category you have nobody in, it goes to your general contacts instead. Keep at least one general contact so nothing is lost.
• A new account starts with one contact: the email of its admin login, in general.

Confirmation

An address has to prove it can receive email before Avenia sends it anything:

• An address that is one of your account's logins is active at once.
• Any other address receives an email from Avenia with a confirmation link and stays pending until someone opens the link and confirms. The link is valid for 7 days.
• A pending contact whose link expired disappears from the list. Add the address again to get a new link.
• If the email got lost, resend the confirmation. The new link restarts the 7 days and the previous one stops working. A contact can get a new link once every 5 minutes.
• Confirmation emails are limited, removed contacts included: one every 5 minutes and at most 5 a day to the same address, and at most 20 a day from your account. Past a limit, adding or resending answers 429 ConfirmationLimitReached.

Only active contacts receive notices.

Suppressed addresses

An address that bounced, marked Avenia's emails as spam or unsubscribed from them is suppressed: it keeps its place in the list, with the reason in the suppression field, but receives nothing. Unsubscribing stops every Avenia notice to that address, whatever the category. Account emails, such as access codes and password resets, are not affected.

A suppressed address cannot be added as a new contact. Contact Avenia support to receive notices there again.

The contact object

Field	Type	Description
id	string	The contact ID, used to change or remove it.
email	string	The address, in lower case.
categories	array	The categories it receives notices for.
status	string	PENDING until the address confirms, then ACTIVE.
suppression	object | null	null, or the reason (bounced, complained, unsubscribed or manual) and since date.
expiresAt	string	Pending contacts only: when the confirmation link stops working.
confirmedAt	string	Active contacts only: when the address was confirmed.
createdAt	string	When the contact was added.
updatedAt	string	When the contact last changed.

List the contacts

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/contacts/

cURL Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/notifications/contacts/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "contacts": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "email": "admin@company.com",
      "categories": ["general"],
      "status": "ACTIVE",
      "suppression": null,
      "confirmedAt": "2026-09-01T12:00:00Z",
      "createdAt": "2026-09-01T12:00:00Z",
      "updatedAt": "2026-09-01T12:00:00Z"
    },
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "email": "finance@company.com",
      "categories": ["finance", "compliance"],
      "status": "PENDING",
      "suppression": null,
      "expiresAt": "2026-09-30T12:00:00Z",
      "createdAt": "2026-09-23T12:00:00Z",
      "updatedAt": "2026-09-23T12:00:00Z"
    }
  ]
}

Add a contact

HTTP Post Request

https://api.sandbox.avenia.io:10952/v2/notifications/contacts/

Parameters

Required

Field	Type	Description
email	string	The address that will receive notices.

Optional

Field	Type	Description
categories	array	The categories it receives. Omitted or empty means general.

cURL Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/notifications/contacts/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "email": "finance@company.com",
  "categories": ["finance", "compliance"]
}'

JSON Response

201 Created with the new contact. This address is not one of the account's logins, so it is pending and has just received its confirmation link:

{
  "id": "00000000-0000-0000-0000-000000000002",
  "email": "finance@company.com",
  "categories": ["finance", "compliance"],
  "status": "PENDING",
  "suppression": null,
  "expiresAt": "2026-09-30T12:00:00Z",
  "createdAt": "2026-09-23T12:00:00Z",
  "updatedAt": "2026-09-23T12:00:00Z"
}

Change the categories of a contact

The categories you send replace the current ones. The status does not change: a confirmed address stays confirmed.

HTTP Patch Request

https://api.sandbox.avenia.io:10952/v2/notifications/contacts/{contactId}

Parameters

Optional

Field	Type	Description
categories	array	The new categories. Omitted or empty means general, so a body without it resets the contact.

cURL Example

curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/notifications/contacts/00000000-0000-0000-0000-000000000002" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "categories": ["finance"]
}'

JSON Response

200 OK with the updated contact, in the same shape as above.

Remove a contact

HTTP Delete Request

https://api.sandbox.avenia.io:10952/v2/notifications/contacts/{contactId}

cURL Example

curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/notifications/contacts/00000000-0000-0000-0000-000000000002" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The response is 204 No Content, with no body.

Resend the confirmation link

For a pending contact only. The new link is valid for 7 days, and the previous one stops working.

HTTP Post Request

https://api.sandbox.avenia.io:10952/v2/notifications/contacts/{contactId}/resend-confirmation

cURL Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/notifications/contacts/00000000-0000-0000-0000-000000000002/resend-confirmation" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

200 OK with the pending contact and its new expiresAt.

Errors

Errors come as JSON with an error code and, for most of them, an extraInfo sentence:

{
  "error": "NotificationContactLimitReached",
  "extraInfo": "category finance already has 10 contacts"
}

Status	error	When
400	InvalidFieldError: email is invalid	The address is not a valid email.
400	InvalidFieldError: categories is invalid	A category is not one of the six above. extraInfo names it.
400	InvalidFieldError: contact-id is invalid	The contact ID in the path is not a valid ID.
400	InvalidBodyError: could not parse body data	The body is not valid JSON.
401	UnauthorizedError	The token or the API key is missing or invalid.
403	ForbiddenError	A login that is not an admin tried to add, change or remove a contact, or resend a link.
404	NotFoundError: notification contact not found	No contact of your account has that ID.
409	NotificationContactAlreadyExists	The address is already a contact. Change its categories instead.
409	NotificationContactNotPending	Resend on a contact that is already confirmed.
422	NotificationContactLimitReached	One of the categories already has 10 addresses.
422	EmailSuppressed	The address is suppressed. Contact Avenia support.
429	ConfirmationResendTooSoon	The last link went out less than 5 minutes ago. extraInfo says how long to wait.
429	ConfirmationLimitReached	Too many confirmation emails went to the address or from your account (see Confirmation). extraInfo says how long to wait.
500	InternalError: please contact us	Something failed on Avenia's side. Try again, and contact support if it persists.
502	ConfirmationMailSendFailed	The confirmation email could not be sent. When adding, the contact was not created; when resending, the previous link still works. Try again.