{ "openapi": "3.1.0", "info": { "title": "Flexmail email marketing API", "version": "1.2.0", "termsOfService": "https://flexmail.be/en/terms-and-conditions", "description": "# Introduction\n\nThe **Flexmail email marketing API** is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) and is designed to have predictable, resource-oriented URLs.\nIt uses HTTP [authentication](#auth) and [verbs](#overview--requests) for requests and HTTP [status codes](#overview--http-statuses) to indicate success or failures.\n\nJSON is used exclusively as the request and response format, including [error responses](#overview--error-formatting), and for resource representations the [HAL]((https://stateless.group/hal_specification.html)) standard is used.\n\nOur email marketing API will eventually offer all the features that are needed for a full email marketing experience, but at the moment it can be used exclusively for **contact management**.\nFor other features like *sending marketing campaigns* or *creating email messages* we still refer to our available [SOAP services](https://soap.flexmail.eu/documentation).\n\n# Requests\n\nRequests should be done with a JSON payload. Our API uses the conventional [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods):\n\n| Method | Description |\n|---|---|\n| **GET** | Retrieve a (collection of) resource(s). |\n| **POST** | Create a new resource in a collection. |\n| **PUT** | Update an existing resource with its new representation. |\n| **PATCH** | Partially apply modifications to a resource. |\n| **DELETE** | Delete a resource. |\n\n# Responses\nAll of our API calls return JSON response bodies (unless documented otherwise) that include information about the resource including one or more contextual [hypermedia links](#overview--hateoas).\n\n\\* *Properties marked as `read-only` are ignored when used in a request body.*\n\n## HTTP statuses\nWe use conventional [HTTP statuses](https://httpstatuses.com) to indicate the success or failure of an API request:\n\n| Status code | Description |\n|---|---|\n| **200** - OK | Everything worked as expected. |\n| **201** - Created | A resource was created.\n| **204** - No Content | The request was fulfilled but no response body is to be expected. |\n| **400** - Bad Request | The server cannot or will not process the request due to something that is perceived to be a client error. |\n| **401** - Unauthorized | You did not provide a valid access token. |\n| **403** - Forbidden | The access token used does not have the required permissions. |\n| **404** - Not Found | The requested resource does not exist. |\n| **409** - Conflict | The request is correct, but could not be completed due to a conflict with the current state of the target resource. |\n| **5xx** - Server Error | Something went wrong on Flexmail's end. |\n\nIn general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.\n\nReturn codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the resource you are requesting does not exist, or that your request is malformed.\n\nIf you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.\n\n## Error formatting\nThe `4xx` responses from above are formatted according to [RFC7807](https://tools.ietf.org/html/rfc7807).\n\nIn short, it looks something like this:\n```json\n{\n \"title\": \"Bad Request\",\n \"type\": \"about:blank\",\n \"status\": 400,\n \"detail\": \"Some optional extra details about the error\"\n}\n```\nThe `type` property may contain a URI reference [RFC3986](https://tools.ietf.org/html/rfc3986) that identifies the problem type.\nFor a generic error, like the `400 Bad Request` response, this will be the default `about:blank` value, indicating there's no extra documentation about the error response.\n\n\n\n### Validation errors\nA validation error is a specific error that can occur on [a `400 Bad Request` response](#overview--error-formatting). It has an extra `errors` property listing the first validation error(s) that occurred. It contains a [JSON pointer](https://tools.ietf.org/html/rfc6901), a human-friendly message and the type of constraint that was violated.\n```json\n{\n \"title\": \"Input validation failed\",\n \"type\": \"https://api.flexmail.eu/documentation/#validation-errors\",\n \"status\": 400,\n \"detail\": \"Some optional extra details about the error\",\n \"errors\": [\n {\n \"pointer\": \"#/0/first_name\",\n \"message\": \"Invalid type integer, expected string\",\n \"constraint\": \"type\"\n }\n ]\n}\n```\n\n\n\n### Query parameter error\nA query parameter error is a specific error that can occur on [a `400 Bad Request` response](#overview--error-formatting). It has an extra `parameter` property indicating which query parameter caused the error.\n```json\n{\n \"title\": \"Invalid query parameter\",\n \"type\": \"https://api.flexmail.eu/documentation/#query-parameter-error\",\n \"status\": 400,\n \"detail\": \"Limit must be a positive integer from 1 to 500\",\n \"parameter\": \"limit\"\n}\n```\n\n\n\n### Access error\nAn access error occurs when a client is not authorized to access the requested resource. This can be caused by the following:\n* The authenticated user is explicitly denied access to the resources because they do not have the correct permissions\n* The resource is not included in the current plan of the Flexmail account. More information about what's included in our plans can be found [here](https://flexmail.be/en/pricing)\n\n```json\n{\n \"title\": \"Access to this resource is denied\",\n \"type\": \"https://api.flexmail.eu/documentation/#access-error\",\n \"status\": 403,\n \"detail\": \"You are either not permitted to access this resource or it is not included in your current plan. Read more about Flexmail's plans on our website\"\n}\n```\n\n# HATEOAS\nOur API is truly RESTful as we provide [hypermedia controls](https://restfulapi.net/hateoas/), which allow an API client to dynamically navigate to the appropriate resources by traversing the hypermedia links.\nTo provide a consistent and easy way to hyperlink between resources, our API uses the [Hypertext Application Language](https://stateless.group/hal_specification.html) (HAL) media type as representation format for resources.\n\nThis means that for every `GET` request we will return the `application/hal+json` representation of the resource with its relations expressed in the `_links` field.\n\nThis is how this looks for a single resource\n\n```json\n{\n \"id\": 42,\n \"email\": \"john@flexmail.be\",\n \"first_name\": \"John\",\n \"name\": \"Doe\",\n \"language\": \"nl\",\n \"custom_fields\": {\n \"organisation\": \"Flexmail\",\n \"myOtherCustomField\": \"42\"\n },\n \"_links\": {\n \"self\": {\n \"href\": \"/contacts/42\"\n },\n \"collection\": {\n \"href\": \"/contacts\"\n },\n \"custom-fields\": {\n \"href\": \"/custom-fields\"\n },\n \"sources\": {\n \"href\": \"/contacts/42/sources\"\n }\n }\n}\n```\n\nFor collection resources we will embed the related resources in the `_embedded` field of the resource representation instead of adding them as `_link` relations, because this is more practical to work with.\n\n```json\n{\n \"total\": 2,\n \"limit\": 10,\n \"offset\": 0,\n \"_links\": {\n \"self\": {\n \"href\": \"/contacts\"\n }\n },\n \"_embedded\": {\n \"item\": [\n {\n \"id\": 42,\n \"email\": \"john@flexmail.be\",\n \"first_name\": \"John\",\n \"name\": \"Doe\",\n \"language\": \"nl\",\n \"custom_fields\": {\n \"organisation\": \"Flexmail\",\n \"myOtherCustomField\": \"42\"\n },\n \"_links\": {\n \"self\": {\n \"href\": \"/contacts/42\"\n },\n \"sources\": {\n \"href\": \"/contacts/42/sources\"\n }\n }\n },\n {\n \"id\": 43,\n \"email\": \"doe@flexmail.be\",\n \"first_name\": \"John\",\n \"name\": \"Doe\",\n \"language\": \"nl\",\n \"custom_fields\": {\n \"organisation\": \"Flexmail\",\n \"myOtherCustomField\": \"43\"\n },\n \"_links\": {\n \"self\": {\n \"href\": \"/contacts/43\"\n },\n \"sources\": {\n \"href\": \"/contacts/43/sources\"\n }\n }\n }\n ]\n }\n}\n```\n\n⚠️ *At the moment we only offer a basic set of hypermedia controls for most resources but this will be expanded along the way*\n\n# Pagination\nOur collection resources are (almost always) paginated, they only return a slice of the total collection. That slice can be controlled by using the `limit` and `offset` query parameter.\n\n| Query parameter | Description |\n|---|---|\n| **limit** | The `limit` query parameter sets the amount of items that will be returned. This parameter has an upper limit, and a default value (when not set) that is specific for each endpoint individually. |\n| **offset** | The `offset` parameter sets the amount of items to skip before fetching the amount indicated by `limit`. |\n\nPaginated resources will return responses with the following properties:\n\n| Property | Description |\n|---|---|\n| **total** | The total amount of items in the collection |\n| **limit** | The amount of items in the returned slice of items. |\n| **offset** | The offset of the returned slice of items. |\n\n# Rate Limiting\nRequests that are made via our API are rate limited per Flexmail account, client IP address and endpoint.\nWe currently apply a rate limit of 60 requests per minute. Once you exceed this limit, you will be rate limited until the next cycle starts and during this period we will respond to each request with a HTTP 429 status code.\n\n### Request limit\nEach Flexmail account also has a monthly API request limit* that is determined by the account's current [plan](https://flexmail.be/en/pricing). When this limit is reached, we will respond to each request with a HTTP 429 status code until the next cycle starts.\nGet in touch with us if a custom request limit is required for your account.\n\n\\* *Requests for our email marketing API and SOAP services are aggregated*\n\n# API contract\nThe Flexmail platform uses continuous delivery to be able to deploy updates multiple times a day. This means that we don't have fixed release cycles, but instead release features as soon as they are ready. It also allows us to correct any possible issues very fast.\nWe try to evolve our API according to the needs of our product and strive to keep it backwards compatible for as long as possible.\n\n## Versioning\nSometimes backwards incompatible changes are inevitable and when we need to handle them, we will use one of the following approaches to guarantee a smooth transition to the new behaviour:\n* A new resource (variant) in addition to the existing one\n* Media type versioning via [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation)\n\nBackwards incompatible changes will be announced in advance via all of our available communication channels.\n\n### Backwards compatible changes\nThe following changes are considered to be backwards compatible:\n* Addition of new HTTP resources\n* Support for additional HTTP verbs on existing HTTP resources\n* New optional properties/parameters in HTTP requests\n* Mandatory properties/parameters that become optional in HTTP requests\n* New properties in HTTP responses\n\n### Backwards incompatible changes\nThe following changes are considered to be backwards incompatible:\n* Removal of an existing HTTP resource\n* Removal of a previously supported HTTP verb for an HTTP resource\n* New (or previously optional) required properties/parameters in HTTP requests\n* Removal (or rename) of properties in HTTP responses\n\n\\* *During the beta phase of an API we consider nothing to be backwards incompatible but we will still try to communicate about major changes as much as possible in advance.*\n\n## Deprecation\nAs our API evolves, some resources are superseded by better implementations and should not be used anymore. The goal of the deprecation process is to communicate with clients at runtime if they use deprecated features.\nTo achieve this in a non-breaking fashion we use the [Deprecation](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header) and [Sunset](https://datatracker.ietf.org/doc/html/rfc8594) headers in our HTTP responses.\n\nDuring the deprecation phase of a resource we will add a `Deprecation` header, and - if also planned - a `Sunset` header.\n```\nDeprecation: Tue, 31 Dec 2024 23:59:59 GMT\nSunset: Wed, 31 Dec 2025 23:59:59 GMT\n```\n\nTo add extra context we also add a `Link` header to the HTTP response that links to human-readable documentation that explains the deprecation.\n```\nLink: ; rel=\"deprecation\"; type=\"text/html\"\n```\n\nWhen individual properties/parameters in HTTP requests of responses become deprecated we will flag them as such in our documentation and [OpenAPI schema](https://api.flexmail.eu/documentation/openapi.json).\n\nIf the `Sunset` header is set, we are effectively telling clients at which point they can expect that the resource will stop working.\n\n### Communication\nWe will use 2 types of communication to inform about API changes. Humans will be informed via all of our available communication channels (API docs, blog posts, emails...) and for API clients we will use the previously mentioned HTTP headers.\nThat's why we recommend API clients to monitor these headers closely.\n", "contact": { "email": "api@flexmail.be" }, "x-logo": { "url": "logo.svg", "altText": "Flexmail logo" } }, "tags": [ { "name": "API Root", "description": "The root resource is the only resource that a RESTful client should know because it links to all other resources." }, { "name": "Contacts", "description": "Contacts are the target audience for your communication. This API provides all the necessary features for a proper contact management.\n\nFor more info about contacts, read [the manual](https://en.support.flexmail.eu/article/290-what-does-a-contact-consist-of)." }, { "name": "Opt-in", "description": "Flexmail implements a double opt-in mechanism in the subscription process of contacts. By incorporating email verification in the mechanism a secure process is established which allows consent to be explicitly confirmed through a verification link that is sent via email. During the opt-in process you not only obtain a person's general consent to send him your marketing mails but you can also collect personal data and subscribe him to specific interests.\nAn opt-in is also the only way to resubscribe a former contact or to subscribe someone with a blacklisted email address.\n\nThe purpose and some of the benefits of the additional layer of confirmation that double opt-in implements are:\n\n1. **Enhanced user consent**:\nThe primary purpose of a double opt-in mechanism is to ensure that someone genuinely wants to subscribe to any form of communication. It adds an extra step to the subscription process, required to confirm intent, which helps prevent accidental or unauthorized subscriptions.\n\n2. **Compliance with regulations**:\nDouble opt-in mechanisms align with privacy regulations, such as [GDPR](https://gdpr-info.eu/) (General Data Protection Regulation) and the [CAN-SPAM Act](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business), which emphasize obtaining explicit consent from persons before sending commercial communications. Implementing a double opt-in process helps ensure compliance with these regulations.\n\n3. **Improved list quality**\nDouble opt-in helps to maintain a cleaner and more accurate contacts list. Since these contacts have confirmed their subscription, the list is less likely to include invalid or mistyped email addresses.\n\n4. **Reduced spam complaints**\nA person who confirms its subscription is less likely to mark incoming emails as spam since he has actively expressed his interest. This helps maintain a positive sender reputation and reduces the risk of being flagged by email service providers as a source of spam.\n\n5. **Engaged and responsive audience**\nContacts who go through the double opt-in process are generally more engaged and interested in the content being offered. This results in a more responsive audience, higher open rates, and increased interaction with emails.\n\n6. **Brand credibility**\nImplementing a double opt-in process demonstrates a commitment to transparency and user consent. This builds trust with your contacts and enhances the credibility of your brand, as they are assured that their privacy and preferences are respected." }, { "name": "Custom Fields", "description": "Custom fields can be used to add extra context to your contacts. They can be managed via the Flexmail UI.\n\nFor more info about custom fields, read [the manual](https://en.support.flexmail.eu/article/296-about-contact-fields)." }, { "name": "Interest Labels", "description": "⚠️ **Interest labels are deprecated and superseded by [Interests](https://flexmail.be/en/interests)**\n\n~~The API enables you to [retrieve all interest labels](#get-/interest-labels) for your account and [fetch all interest labels for a specific contact](#get-/contacts/-id-/interest-labels).~~\n\n~~For more info about interest labels, read [the manual](https://en.support.flexmail.eu/article/321-about-interests).~~" }, { "name": "Interests", "description": "Interests are a great way to get a better understanding of your contacts and send them personalised content.\n\nTwo kind of interests exist in Flexmail: public interests, which contacts can subscribe to and unsubscribe from themselves via their profile, or private interests which are never shown to contacts and are a great way to segment them even further based on your own knowledge. To maximize the importance of your contacts' choices, we don't allow you to resubscribe a contact again to a public interest that it unsubscribed from.\n\nFor more information about interests, [read the manual](https://en.support.flexmail.eu/article/1164-new-about-interests)." }, { "name": "Preferences", "description": "⚠️ **Preferences are deprecated and superseded by [Interests](https://flexmail.be/en/interests)**\n\n~~The API enables you to [retrieve all preferences](#get-/preferences) for your account, [subscribe](#post-/contact-preference-subscriptions) & [unsubscribe](#delete-/contact-preference-subscriptions/-id-) contacts from your account to them, and [fetch all preferences for a specific contact](#get-/contacts/-id-/preferences).~~\n\n~~For more info about preferences, read [the manual](https://en.support.flexmail.eu/article/557-about-preferences).~~" }, { "name": "Segments", "description": "Segmentation is a powerful tool for filtering contacts with comparable data in contact fields, interests, actions performed in your campaigns or other information, and for including them in a target group together. You use your segments to bring similar contacts together and view them or to send specific campaigns on the basis of information they have in common.\n\nFor more info about segments, read [the manual](https://en.support.flexmail.eu/article/1210-about-segments)." }, { "name": "Sources", "description": "Sources are Flexmail's way of knowing where contact data originates from. Because of the [GDPR](https://gdpr-info.eu/) each contact in Flexmail is required to have at least 1 source.\n\nFor more info about sources, read [the manual](https://en.support.flexmail.eu/article/291-about-sources)." }, { "name": "Webhooks", "description": "The Flexmail email marketing API uses [webhooks](/documentation/webhooks) for event notification. We allow you to manage your webhooks as subscriptions just like any other API resource. This gives your interested third party applications the opportunity to dynamically create and update integrations that perform in near real-time functions.\n\nFor more information about our webhooks, read [their documentation](/documentation/webhooks)" } ], "components": { "schemas": { "accountContactLanguages": { "type": "object", "properties": { "languages": { "type": "array", "description": "The configured contact languages for the account.", "items": { "type": "string" } }, "default_language": { "type": "string", "description": "The language that will be used as a fallback when labels of specific elements (custom fields, interests...) are not translated into the contact language." }, "_links": { "required": [ "self" ], "type": "object", "properties": { "self": { "$ref": "#/components/schemas/relationLink" } } } }, "example": { "languages": [ "nl", "en", "fr" ], "default_language": "en", "_links": { "self": { "href": "/account-contact-languages" } } } }, "apiInfo": { "allOf": [ { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "object", "description": "Basic information about the authenticated user.", "properties": { "first_name": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" } } } } }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "description": "All the available API resources. This list may vary depending on the configuration of the Flexmail account", "required": [ "self", "sources" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/" } } } ] }, "contacts": { "$ref": "#/components/schemas/contactsRelationLink" }, "custom-fields": { "$ref": "#/components/schemas/customFieldsRelationLink" }, "sources": { "$ref": "#/components/schemas/sourcesRelationLink" }, "interests": { "$ref": "#/components/schemas/interestsRelationLink" }, "interest-labels": { "$ref": "#/components/schemas/interestLabelsRelationLink" }, "preferences": { "$ref": "#/components/schemas/preferencesRelationLink" } } } } } ] }, "apiProblem": { "title": "API problem", "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "description": "A URI reference that identifies the problem type" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type" }, "status": { "type": "integer", "description": "The HTTP status code" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem" } }, "example": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "" } }, "apiProblemWithValidationErrors": { "title": "API Problem with Validation Errors", "allOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "required": [ "errors" ], "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/apiValidationError" } } } } ], "example": { "title": "Input validation failed", "type": "https://api.flexmail.eu/documentation/#validation-errors", "status": 400, "detail": "Some optional extra details about the error", "errors": [ { "pointer": "#/0/first_name", "message": "Invalid type integer, expected string", "constraint": "type" } ] } }, "apiValidationError": { "title": "Validation error", "type": "object", "required": [ "pointer", "message", "constraint" ], "properties": { "pointer": { "type": "string", "description": "A JSON pointer referring to the item in the request that caused the error", "example": "#/0/first_name" }, "message": { "type": "string", "description": "A message explaining the error", "example": "Invalid type integer, expected string" }, "constraint": { "type": "string", "description": "The type of constraint that was violated", "example": "type" } } }, "apiProblemWithInvalidQueryParameterError": { "title": "API Problem with Invalid Query Parameter", "allOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "type": "object", "required": [ "parameter" ], "properties": { "parameter": { "type": "string" } } } ], "example": { "title": "Invalid query parameter", "type": "https://api.flexmail.eu/documentation/#query-parameter-error", "status": 400, "detail": "Limit must be a positive integer from 1 to 500", "parameter": "limit" } }, "baseRelationLinks": { "type": "object", "required": [ "_links" ], "properties": { "_links": { "type": "object", "readOnly": true, "required": [ "self" ], "properties": { "self": { "$ref": "#/components/schemas/relationLink" } } } } }, "collectionProperties": { "type": "object", "required": [ "total", "limit", "offset" ], "properties": { "total": { "$ref": "#/components/schemas/collectionTotal" }, "limit": { "$ref": "#/components/schemas/sliceLimit" }, "offset": { "$ref": "#/components/schemas/sliceOffset" } } }, "collectionTotal": { "type": "integer", "minimum": 0, "example": 42 }, "compoundId": { "title": "Compound id", "type": "string", "example": "42+29", "description": "The primary identifier for the resource\n\nThese kind of ids are composed out of the primary identifiers from the parts that make up a many-2-many relation." }, "contact": { "title": "Contact", "type": "object", "required": [ "id", "email", "language" ], "properties": { "id": { "$ref": "#/components/schemas/internalId" }, "email": { "type": "string", "format": "email", "readOnly": true, "example": "john@flexmail.be", "maxLength": 200 }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "name": { "type": "string", "maxLength": 50, "example": "Doe" }, "language": { "description": "The language the contact wants to receive emails in.\n\nNOTE: The list of allowed languages may be further restricted depending on the [configured account contact languages](#get-/account-contact-languages).", "allOf": [ { "$ref": "#/components/schemas/supportedLanguage" } ] }, "custom_fields": { "$ref": "#/components/schemas/customFieldValues" } }, "additionalProperties": false }, "contactLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "collection", "sources" ], "properties": { "self": { "$ref": "#/components/schemas/contactRelationLink" }, "collection": { "$ref": "#/components/schemas/contactsRelationLink" }, "sources": { "$ref": "#/components/schemas/contactSourceSubscriptionsRelationLink" } } } } } ] }, "contactRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/42" } } } ] }, "contacts": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self" ], "properties": { "self": { "$ref": "#/components/schemas/contactsRelationLink" } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/contact" }, { "required": [ "first_name", "name" ] }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "sources" ], "properties": { "self": { "$ref": "#/components/schemas/contactRelationLink" }, "sources": { "$ref": "#/components/schemas/contactSourceSubscriptionsRelationLink" } } } } } ] } } } } } } ] }, "contactsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts" } } } ] }, "contactImport": { "allOf": [ { "type": "object", "required": [ "id", "status", "report" ], "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "status": { "$ref": "#/components/schemas/contactImportStatus" }, "report": { "oneOf": [ { "title": "No report", "type": "null", "description": "There will be no report until the import is completed" }, { "$ref": "#/components/schemas/importReportExternal" } ], "description": "A report with detailed information about the processed import" } } }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact-import-records" ], "properties": { "self": { "$ref": "#/components/schemas/contactImportRelationLink" }, "contact-import-records": { "$ref": "#/components/schemas/contactImportRecordsRelationLink" } } } } } ] }, "contactImportRecordsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/imports/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f/records" } } } ] }, "contactImportRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/imports/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f" } } } ] }, "contactImportRecordRelationsDeprecated": { "type": "object", "properties": { "interest_labels": { "type": "array", "description": "⚠️ *This property is **deprecated** and will be ignored if your account is using the [interests](https://flexmail.be/en/interests) feature*\n\nIDs of interest labels to which the contact needs to be subscribed.", "items": { "allOf": [ { "$ref": "#/components/schemas/interestLabelId" }, { "readOnly": false, "deprecated": true } ] } }, "preferences": { "type": "array", "description": "⚠️ *This property is **deprecated** and will be ignored if your account is using the [interests](https://flexmail.be/en/interests) feature*\n\nIDs of preferences to which the contact needs to be subscribed.", "items": { "allOf": [ { "$ref": "#/components/schemas/preferenceId" }, { "readOnly": false, "deprecated": true } ] } } } }, "contactImportRecordRelations": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "description": "IDs of sources that need to be coupled to the contact. The available sources of the account can be [listed](#get-/sources)", "minItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/sourceId" }, { "readOnly": false } ] } }, "interests": { "type": "array", "description": "🔒️ *This property can only be used if your account is using the [interests](https://flexmail.be/en/interests) feature, otherwise it will be removed*\n\nIDs of interests to which the contact needs to be subscribed.", "items": { "allOf": [ { "$ref": "#/components/schemas/interestId" }, { "readOnly": false } ] } } } }, "contactImportStart": { "allOf": [ { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/contactImportStatus" } } }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact-import" ], "properties": { "self": { "$ref": "#/components/schemas/contactImportStartRelationLink" }, "contact-import": { "$ref": "#/components/schemas/contactImportRelationLink" } } } } } ] }, "contactImportStartRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/imports/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f/start" } } } ] }, "contactImportStatus": { "type": "string", "description": "The status of the import", "enum": [ "idle", "queued", "processing", "completed", "rejected", "failed" ] }, "contactInterestLabels": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/contactInterestLabelSubscriptionsRelationLink" }, { "properties": { "href": { "example": "/contacts/29/interest-labels" } } } ] }, "contact": { "allOf": [ { "$ref": "#/components/schemas/contactRelationLink" }, { "properties": { "href": { "example": "/contacts/29" } } } ] } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/interestLabelDeprecated" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact-interest-label-subscription" ], "properties": { "self": { "$ref": "#/components/schemas/interestLabelRelationLink" }, "contact-interest-label-subscription": { "$ref": "#/components/schemas/contactInterestLabelSubscriptionRelationLink" } } } } } ] } } } } } } ] }, "contactInterestLabelSubscriptionRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contact-interest-label-subscriptions/29+42" } } } ] }, "contactInterestLabelSubscriptionsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/42/interest-labels" } } } ] }, "contactPatch": { "title": "Contact", "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "name": { "type": "string", "maxLength": 50, "example": "Doe" }, "language": { "description": "The language the contact wants to receive emails in.\n\nNOTE: The list of allowed languages may be further restricted depending on the [enabled account contact languages](#get-/account-contact-languages).", "allOf": [ { "$ref": "#/components/schemas/supportedLanguage" } ] }, "custom_fields": { "allOf": [ { "$ref": "#/components/schemas/customFieldValues" }, { "description": "A value for one of your account's custom fields for this contact. \nSince custom fields are unique to your account it could be anything. \nFor example: `\"organisation_name\": \"Flexmail\"`\n\nWhen using this resource in a request (`PATCH` for example) you must provide them with the placeholder name as key." } ] } }, "additionalProperties": false, "minProperties": 1 }, "contactPreferences": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/contactPreferenceSubscriptionsRelationLink" }, { "properties": { "href": { "example": "/contacts/29/preferences" } } } ] }, "contact": { "allOf": [ { "$ref": "#/components/schemas/contactRelationLink" }, { "properties": { "href": { "example": "/contacts/29" } } } ] } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/preference" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact-preference-subscription" ], "properties": { "self": { "$ref": "#/components/schemas/preferenceRelationLink" }, "contact-preference-subscription": { "$ref": "#/components/schemas/contactPreferenceSubscriptionRelationLink" } } } } } ] } } } } } } ] }, "contactPreferenceSubscriptionRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contact-preference-subscriptions/29+42" } } } ] }, "contactPreferenceSubscriptionsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/42/preferences" } } } ] }, "contactSourceSubscriptionsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/42/sources" } } } ] }, "contactSources": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/contactSourceSubscriptionsRelationLink" }, { "properties": { "href": { "example": "/contacts/29/sources" } } } ] }, "contact": { "allOf": [ { "$ref": "#/components/schemas/contactRelationLink" }, { "properties": { "href": { "example": "/contacts/29" } } } ] } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/source" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/sourceRelationLink" } } } } } ] } } } } } } ] }, "customFieldId": { "$ref": "#/components/schemas/uuid" }, "customFieldName": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The name of the custom field, translated in the requested language (see the `language` query parameter) or, when omitted, the account's default contact language. It has a maximum length of 50 characters." }, "customFieldOption": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The name of the option, translated in the requested language (see the `language` query parameter) or, when omitted, the account's default contact language." }, "value": { "type": "string", "description": "The stored value of the option." } } }, "customField": { "oneOf": [ { "$ref": "#/components/schemas/customFieldFreeText" }, { "$ref": "#/components/schemas/customFieldMultipleChoice" }, { "$ref": "#/components/schemas/customFieldNumeric" }, { "$ref": "#/components/schemas/customFieldDate" } ] }, "customFieldFreeText": { "title": "Free text field", "description": "Default representation of the custom field resource", "type": "object", "additionalProperties": false, "required": [ "id", "type", "placeholder", "name" ], "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "type": { "type": "string", "enum": [ "free_text" ], "description": "The type of the custom field." }, "placeholder": { "$ref": "#/components/schemas/placeholder" }, "name": { "$ref": "#/components/schemas/customFieldName" } } }, "customFieldNumeric": { "title": "Numeric field", "description": "Default representation of the custom field resource", "type": "object", "additionalProperties": false, "required": [ "id", "type", "placeholder", "name" ], "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "type": { "type": "string", "enum": [ "numeric" ], "description": "The type of the custom field." }, "placeholder": { "$ref": "#/components/schemas/placeholder" }, "name": { "$ref": "#/components/schemas/customFieldName" } } }, "customFieldDate": { "title": "Date field", "description": "Default representation of the custom field resource", "type": "object", "additionalProperties": false, "required": [ "id", "type", "placeholder", "name" ], "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "type": { "type": "string", "enum": [ "date" ], "description": "The type of the custom field." }, "placeholder": { "$ref": "#/components/schemas/placeholder" }, "name": { "$ref": "#/components/schemas/customFieldName" } } }, "customFieldMultipleChoice": { "title": "Multiple choice field", "description": "Default representation of the custom field resource", "type": "object", "additionalProperties": false, "required": [ "id", "type", "placeholder", "name", "allows_multiple_values", "options" ], "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "type": { "type": "string", "enum": [ "multiple_choice" ], "description": "The type of the custom field." }, "placeholder": { "$ref": "#/components/schemas/placeholder" }, "name": { "$ref": "#/components/schemas/customFieldName" }, "allows_multiple_values": { "type": "boolean", "description": "Whether the custom field allows selecting multiple options as values." }, "options": { "type": "array", "description": "All available options for the custom field.", "items": { "$ref": "#/components/schemas/customFieldOption" } } } }, "customFields": { "allOf": [ { "type": "object", "required": [ "total" ], "properties": { "total": { "$ref": "#/components/schemas/collectionTotal" } } }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/customFieldsRelationLink" } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "$ref": "#/components/schemas/customField" } } } } } } ] }, "customFieldType": { "type": "string", "enum": [ "free_text", "numeric", "date", "multiple_choice" ], "description": "The type of the custom field." }, "customFieldsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/custom-fields" } } } ] }, "customFieldValues": { "type": "object", "description": "A value for one of your account's custom fields for this contact. \nSince custom fields are unique to your account it could be anything. \nFor example: `\"organisation_name\": \"Flexmail\"`\n\nWhen using this resource in a request (`PUT` for example) you must provide them with the placeholder name as key. Providing any other additional properties, i.e. a nonexistent placeholder, will result in a `400` response.", "additionalProperties": { "oneOf": [ { "type": "string", "title": "Custom free text field" }, { "type": "string", "format": "date", "title": "Custom date field" }, { "type": "number", "title": "Custom numeric field" }, { "type": "array", "title": "Custom multiple choice field", "items": { "title": "Multiple choice option", "type": "string" } }, { "type": "null", "title": "Empty" } ] }, "example": { "organisation": "Flexmail", "myOtherCustomField": "42" } }, "headerDeprecation": { "type": "string", "pattern": "^Deprecation: ([a-zA-Z]{3}, [0-9]{1,2} [a-zA-Z]{3} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2] GMT|true)$" }, "headerLocation": { "type": "string", "format": "uri-template" }, "headerSunset": { "type": "string", "pattern": "^Deprecation: ([a-zA-Z]{3}, [0-9]{1,2} [a-zA-Z]{3} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2] GMT|true)$" }, "importReportExternal": { "title": "An import report", "type": "object", "required": [ "total_added", "total_updated", "total_ignored" ], "properties": { "total_added": { "type": "integer", "description": "The amount of contacts that were created by this import", "minimum": 0 }, "total_updated": { "type": "integer", "description": "The amount of contacts that were updated by this import", "minimum": 0 }, "total_ignored": { "type": "integer", "description": "The amount of records that were ignored during the import. They were ignored because the email in the record is blacklisted.", "minimum": 0 } } }, "interest": { "type": "object", "required": [ "id", "name", "visibility", "label", "description" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[^,]*$", "description": "The name of the interest. This is the internal name that is used in the Flexmail account.", "example": "Programming" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "label": { "$ref": "#/components/schemas/interestLabel" }, "description": { "$ref": "#/components/schemas/interestDescription" } } }, "interestDescription": { "type": "string", "maxLength": 100, "description": "The description of the interest. Can be used in all contact facing UIs and communication to add context to this interest. If your account is configured to have multiple contact languages it is also translatable.", "example": "Let me know everything about programming!" }, "interestLabel": { "type": "string", "maxLength": 50, "description": "The label of the interest. This is the public name that is used in all contact facing UIs and communication. If your account is configured to have multiple contact languages it is also translatable.", "example": "Programming" }, "interestLabelDeprecated": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/internalId" }, "name": { "type": "string", "minLength": 1, "example": "Programming" } } }, "interestId": { "$ref": "#/components/schemas/uuid" }, "interestLabelId": { "$ref": "#/components/schemas/internalId" }, "interestLabelRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/interest-labels/42" } } } ] }, "interestLabels": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/interestLabelsRelationLink" } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/interestLabelDeprecated" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/interestLabelRelationLink" } } } } } ] } } } } } } ] }, "interestLabelsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/interest-labels" } } } ] }, "interestLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "collection", "translations" ], "properties": { "self": { "$ref": "#/components/schemas/interestRelationLink" }, "collection": { "$ref": "#/components/schemas/interestsRelationLink" }, "translations": { "$ref": "#/components/schemas/interestTranslationRelationLink" } } } } } ] }, "interestPatchInput": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "The fields to update on an interest. Only provided fields will be changed.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[^,]*$", "description": "The name of the interest. This is the internal name that is used in the Flexmail account.", "example": "Programming" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "label": { "$ref": "#/components/schemas/interestLabel" }, "description": { "$ref": "#/components/schemas/interestDescription" } } }, "interestPostInput": { "type": "object", "required": [ "name", "visibility" ], "additionalProperties": false, "description": "The fields required to create a new interest.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[^,]*$", "description": "The name of the interest. This is the internal name that is used in the Flexmail account.", "example": "Programming" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "label": { "$ref": "#/components/schemas/interestLabel" }, "description": { "$ref": "#/components/schemas/interestDescription" } } }, "interestRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/interests/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f" } } } ] }, "interestSubscription": { "type": "object", "required": [ "interest_id" ], "properties": { "interest_id": { "$ref": "#/components/schemas/uuid" }, "_links": { "required": [ "self", "contact" ], "properties": { "self": { "$ref": "#/components/schemas/interestSubscriptionRelationLink" }, "contact": { "$ref": "#/components/schemas/contactRelationLink" } } }, "_embedded": { "type": "object", "properties": { "interest": { "allOf": [ { "type": "object", "required": [ "id", "name", "visibility" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "default": "public" } } }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/interestRelationLink" } } } } } ] } } } } }, "interestSubscriptionRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/42/interest-subscriptions/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f" } } } ] }, "interestSubscriptions": { "allOf": [ { "type": "object", "additionalProperties": false, "required": [ "total" ], "properties": { "total": { "$ref": "#/components/schemas/collectionTotal" } } }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "contact" ], "properties": { "self": { "$ref": "#/components/schemas/interestSubscriptionsRelationLink" }, "contact": { "$ref": "#/components/schemas/contactRelationLink" } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "$ref": "#/components/schemas/interestSubscription" } } } } } } ] }, "interestSubscriptionsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/contacts/42/interest-subscriptions" } } } ] }, "interestTranslationRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/interests/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f/translations" } } } ] }, "interestTranslations": { "type": "object", "required": [ "label_translations", "description_translations" ], "additionalProperties": false, "properties": { "label_translations": { "type": "object", "description": "Translations for the interest label, keyed by language code. Keys must be language codes of the [account's configured contact languages(#get-/account-contact-languages)].", "additionalProperties": { "$ref": "#/components/schemas/interestLabel" }, "example": { "nl": "Programmeren", "en": "Programming" } }, "description_translations": { "type": "object", "description": "Translations for the interest description, keyed by language code. Keys must be language codes of the [account's configured contact languages](#get-/account-contact-languages).", "additionalProperties": { "$ref": "#/components/schemas/interestDescription" }, "example": { "nl": "Ik wil alles weten over programmeren!", "en": "Let me know everything about programming!" } } } }, "interestTranslationsLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "interest" ], "properties": { "self": { "$ref": "#/components/schemas/interestTranslationRelationLink" }, "interest": { "$ref": "#/components/schemas/interestRelationLink" } } } } } ] }, "interestVisibility": { "type": "string", "enum": [ "public", "private" ] }, "interests": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "properties": { "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/interest" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/interestRelationLink" } } } } } ] } } } } } } ] }, "interestsLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/interestsRelationLink" } } } } } ] }, "interestsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/interests" } } } ] }, "internalId": { "title": "Numeric id", "type": "integer", "minimum": 1, "description": "Primary identifier for the resource", "example": 42, "readOnly": true }, "internalIdForRelation": { "title": "Id of a related resource", "allOf": [ { "$ref": "#/components/schemas/internalId" }, { "readOnly": false, "description": "" } ], "example": 42 }, "genericResourceWithOnlyItsUuid": { "type": "object", "description": "A simple representation of a resource consisting of only its identifier", "properties": { "id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id" ], "additionalProperties": false }, "genericResourceWithOnlyItsNumericIdentifier": { "type": "object", "description": "A simple representation of a resource consisting of only its identifier", "properties": { "id": { "$ref": "#/components/schemas/internalId" } }, "required": [ "id" ], "additionalProperties": false }, "optIn": { "type": "object", "required": [ "email", "opt_in_form_id" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "example": "john@flexmail.be", "maxLength": 200, "description": "The email address of the contact that is subscribing to your communication. The opt-in confirmation mail will be sent to this address." }, "opt_in_form_id": { "type": "integer", "description": "The identifier of the opt-in form whose email config will be used to send the opt-in mail, and to whose interests the contact will be subscribed to if the opt-in is confirmed.", "example": 4 }, "first_name": { "type": "string", "example": "John", "maxLength": 50, "description": "The first name of the contact. URLs are not allowed." }, "name": { "type": "string", "example": "Doe", "maxLength": 50, "description": "The name of the contact. URLs are not allowed." }, "language": { "description": "The language of the contact. If not provided, the language of the opt-in form will be used instead.\n\nNOTE: The list of allowed languages may be further restricted depending on [the enabled account contact languages](#get-/account-contact-languages).", "allOf": [ { "$ref": "#/components/schemas/supportedLanguage" } ] }, "custom_fields": { "allOf": [ { "$ref": "#/components/schemas/customFieldValues" }, { "description": "A value for one of your account's custom fields for this opt-in. \nSince custom fields are unique to your account it could be anything. \nFor example: `\"organisation_name\": \"Flexmail\"`\n\nWhen using this resource in a request, you must provide them with the placeholder name as key." } ] } } }, "optInForm": { "type": "object", "required": [ "id", "name", "language", "fields", "email_config", "interests" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/internalId" }, "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "language": { "description": "The language of the form.\n\nNOTE: The list of allowed languages may be further restricted depending on the enabled account contact languages.", "allOf": [ { "$ref": "#/components/schemas/supportedLanguage" } ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2023-07-06T20:20:39+00:00" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/optInFormField" }, "minItems": 1, "description": "At minimum this has to have the `email` field as a required field" }, "email_config": { "$ref": "#/components/schemas/optInFormEmailConfig" }, "interests": { "type": "array", "items": { "$ref": "#/components/schemas/uuidForRelation" }, "maxItems": 5, "description": "The (uuids of the) interests to which a contact should be subscribed when opting in via this form." } } }, "optInFormDetail": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/internalId" }, "name": { "type": "string", "description": "The display name of the opt-in form." }, "language": { "description": "The language of the opt-in form.\n\nNOTE: The list of allowed languages may be further restricted depending on [the enabled account contact languages](#get-/account-contact-languages).", "allOf": [ { "$ref": "#/components/schemas/supportedLanguage" } ] }, "created_at": { "type": "string", "format": "date-time", "example": "2023-07-06T20:20:39+00:00", "description": "The timestamp when the opt-in form was created." } }, "example": { "id": 42, "name": "blog", "language": "nl", "created_at": "2023-07-06T20:20:39+00:00" } }, "optInFormDetailRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/opt-in-forms/1" } } } ] }, "optInFormEmailConfig": { "type": "object", "required": [ "subject", "from_name", "from_email", "reply_to_email" ], "additionalProperties": false, "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 250 }, "from_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "from_email": { "type": "string", "minLength": 5, "maxLength": 255, "example": "foo@bar.com" }, "reply_to_email": { "type": "string", "minLength": 5, "maxLength": 255, "example": "foo@bar.com" } } }, "optInFormField": { "type": "object", "required": [ "id", "required", "rank" ], "additionalProperties": false, "properties": { "id": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/customFieldId" }, { "title": "uuid of a custom field", "readOnly": false, "description": "A (uuid of a) custom field that needs to be shown on this opt-in form" } ] }, { "type": "string", "title": "default field", "enum": [ "email", "first_name", "name" ], "description": "A default field that needs to be shown on this opt-in form" } ] }, "required": { "type": "boolean" }, "rank": { "type": "integer", "minimum": 0 } }, "example": { "id": "email", "required": true, "rank": 1 } }, "optInFormLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "collection" ], "properties": { "self": { "$ref": "#/components/schemas/optInFormRelationLink" }, "collection": { "$ref": "#/components/schemas/optInFormsRelationLink" } } } } } ] }, "optInFormRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/opt-in-forms/42" } } } ] }, "optInForms": { "type": "object", "description": "A collection of active opt-in forms.", "properties": { "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/optInFormDetail" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/optInFormDetailRelationLink" } } } } } ] } } } } } }, "optInFormsLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/opt-in-forms" } } } ] }, "optInFormsLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/optInFormsLink" } } } } } ] }, "optInFormsRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/opt-in-forms" } } } ] }, "placeholder": { "type": "string", "pattern": "^[a-z_0-9]{1,50}$", "description": "A unique value for each field. Refer to our documentation for a [list of reserved placeholders](https://en.support.flexmail.eu/article/383-personalise-with-placeholders) which cannot be used as a custom field placeholder.", "readOnly": true, "example": "custom_field_placeholder" }, "preference": { "type": "object", "required": [ "id", "title", "label", "description" ], "properties": { "id": { "$ref": "#/components/schemas/internalId" }, "title": { "type": "string", "minLength": 1, "description": "How the preference will be shown in the UI to you", "example": "Monthly newsletter" }, "label": { "type": "string", "minLength": 1, "description": "How the preference will be shown to your contacts", "example": "Subscribe to our monthly newsletter" }, "description": { "type": "string", "description": "An optional extra description to show to your contacts for extra context", "example": "Once a month the most recent news in your inbox" } } }, "preferenceLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "collection" ], "properties": { "self": { "$ref": "#/components/schemas/preferenceRelationLink" }, "collection": { "$ref": "#/components/schemas/preferencesRelationLink" } } } } } ] }, "preferenceRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/preferences/42" } } } ] }, "preferences": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/preferencesRelationLink" } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/preference" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/preferenceRelationLink" } } } } } ] } } } } } } ] }, "preferencesRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/preferences" } } } ] }, "preferenceId": { "$ref": "#/components/schemas/internalId" }, "relationLink": { "type": "object", "additionalProperties": false, "properties": { "href": { "type": "string", "description": "A relative uri" } } }, "segments": { "title": "A collection of segments", "description": "A collection of all the active segments.", "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "number_of_contacts" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The identifier of the segment." }, "parent_id": { "type": "string", "format": "uuid", "description": "The identifier of the segment's parent. Absent if the segment has no parent." }, "name": { "type": "string", "description": "A human readable name for the segment." }, "number_of_contacts": { "type": "integer", "description": "The number of contacts in this segment." }, "last_campaign_date": { "type": "string", "format": "date-time", "description": "The date when a campaign was last sent to this segment. Absent if no campaign has ever been sent to this segment." } } } } } } } }, "segmentsLinks": { "title": "segmentsLinks", "type": "object", "properties": { "_links": { "type": "object", "properties": { "self": { "$ref": "#/components/schemas/relationLink" } } } }, "examples": [ { "_links": { "self": { "href": "/segments" } } } ] }, "sliceLimit": { "type": "integer", "default": 25, "minimum": 1, "maximum": 500, "example": 10 }, "sliceOffset": { "type": "integer", "default": 0, "minimum": 0 }, "source": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/internalId" }, "name": { "type": "string", "minLength": 1, "example": "newsletter signup form" } } }, "sourceId": { "$ref": "#/components/schemas/internalId" }, "sourceLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "collection" ], "properties": { "self": { "$ref": "#/components/schemas/sourceRelationLink" }, "collection": { "$ref": "#/components/schemas/sourcesRelationLink" } } } } } ] }, "sourceRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/sources/42" } } } ] }, "sources": { "allOf": [ { "$ref": "#/components/schemas/collectionProperties" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/sourcesRelationLink" } } }, "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/source" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/sourceRelationLink" } } } } } ] } } } } } } ] }, "sourcesRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/sources" } } } ] }, "supportedLanguage": { "title": "Supported language", "type": "string", "enum": [ "nl", "fr", "de", "it", "es", "ru", "da", "se", "zh", "pt", "pl", "en", "hu", "bg", "hr", "cs", "et", "fi", "el", "ga", "lv", "lt", "mt", "ro", "sk", "sl", "uk", "ca" ] }, "uuid": { "title": "Uuid", "type": "string", "format": "uuid", "description": "Primary identifier for the resource", "example": "e8f4143f-edd0-4f0a-8ea9-c674c049fe4f", "readOnly": true }, "uuidForRelation": { "title": "Uuid of a related resource", "allOf": [ { "$ref": "#/components/schemas/uuid" }, { "readOnly": false, "description": "" } ] }, "uuidProvidedByClient": { "allOf": [ { "$ref": "#/components/schemas/uuid" }, { "description": "Primary identifier for the resource.\n\nYou can optionally provide your own UUID. This could result in a `409 Conflict` response if the UUID is already known.\n", "readOnly": false } ] }, "webhookLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "required": [ "self", "collection" ], "properties": { "self": { "$ref": "#/components/schemas/webhookRelationLink" }, "collection": { "$ref": "#/components/schemas/webhooksRelationLink" } } } } } ] }, "webhookRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/webhooks/e8f4143f-edd0-4f0a-8ea9-c674c049fe4f" } } } ] }, "webhooksRelationLink": { "allOf": [ { "$ref": "#/components/schemas/relationLink" }, { "properties": { "href": { "example": "/webhooks" } } } ] }, "webhook": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "event_name": { "description": "The name of the event that triggers the webhook.", "type": "string", "example": "contact.created" }, "target_url": { "description": "The target URL that will receive the HTTP callback when the webhook is triggered. Must use HTTPS.", "type": "string", "format": "uri", "example": "https://example.org/webhook-receiver" }, "verification_token": { "$ref": "#/components/schemas/webhookVerificationToken" }, "enabled": { "description": "A webhook will get disabled after 10 failed retries", "type": "boolean", "example": true } } }, "webhooks": { "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "item": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/webhook" }, { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/webhookRelationLink" } } } } } ] } } } } } }, "webhooksLinks": { "allOf": [ { "$ref": "#/components/schemas/baseRelationLinks" }, { "properties": { "_links": { "properties": { "self": { "$ref": "#/components/schemas/webhooksRelationLink" } } } } } ] }, "webhookVerificationToken": { "type": "string", "title": "Verification token", "description": "Token to verify the identity of the receiver. If empty, a random token will be generated.", "example": "4b57fg1ck4i2", "minLength": 12, "maxLength": 40, "pattern": "^[a-zA-Z0-9]{12,40}$" } }, "headers": { "location": { "schema": { "$ref": "#/components/schemas/headerLocation" }, "description": "The URI of the newly created resource.", "required": true }, "deprecation": { "schema": { "$ref": "#/components/schemas/headerDeprecation" }, "description": "Deprecation header for a resource according to https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header", "required": true }, "sunset": { "schema": { "$ref": "#/components/schemas/headerSunset" }, "description": "Sunset header for a resource according to https://datatracker.ietf.org/doc/html/rfc8594", "required": true } }, "parameters": { "compoundId": { "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/compoundId" }, "description": "The primary identifier for the resource\n\nThese kind of ids are composed out of the primary identifiers from the parts that make up a many-2-many relation.", "required": true }, "contactLanguage": { "name": "language", "in": "query", "description": "Determines the language in which the custom field and multiple choice option names are returned. Must be one of the account's [configured contact languages](#get-/account-contact-languages). When omitted, the account's default contact language is used.", "schema": { "$ref": "#/components/schemas/supportedLanguage" } }, "customFieldType": { "name": "type", "in": "query", "description": "Limits the returned custom fields to the ones of the given type.", "schema": { "$ref": "#/components/schemas/customFieldType" } }, "email": { "in": "query", "name": "email", "description": "An email address to filter on. Cannot be combined with the `interest` filter.", "schema": { "type": "string", "format": "email" } }, "id": { "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/internalId" }, "required": true, "description": "The primary identifier for the resource" }, "interest": { "in": "query", "name": "interest", "description": "The id of a single interest to filter on. Only one interest id is allowed. Only contacts actively subscribed to this interest are returned. Cannot be combined with the `email` filter.", "schema": { "$ref": "#/components/schemas/interestId" } }, "interestName": { "name": "name", "in": "query", "description": "Limits the returned interests to the ones whose name contains the given name", "schema": { "type": "string" } }, "interestOrderBy": { "name": "order_by", "in": "query", "description": "Orders the results by this property", "schema": { "allOf": [ { "$ref": "#/components/parameters/orderBy/schema" }, { "enum": [ "name" ], "default": "name" } ] } }, "interestVisibility": { "name": "visibility", "in": "query", "description": "Limit the returned interests to the ones that are public/private", "schema": { "$ref": "#/components/schemas/interestVisibility" } }, "orderBy": { "name": "order_by", "in": "query", "description": "Orders the results by this property", "schema": { "type": "string" } }, "orderDirection": { "name": "order_direction", "in": "query", "description": "Whether the results should be sorted asc(ending) or desc(ending)", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, "descOrderDirection": { "name": "order_direction", "in": "query", "description": "Whether the results should be sorted asc(ending) or desc(ending)", "schema": { "allOf": [ { "$ref": "#/components/parameters/orderDirection/schema" }, { "default": "desc" } ] } }, "sliceLimit": { "in": "query", "name": "limit", "description": "The amount of items the response should contain", "schema": { "$ref": "#/components/schemas/sliceLimit" } }, "sliceOffset": { "in": "query", "name": "offset", "description": "Determines the offset to start the slice from", "schema": { "$ref": "#/components/schemas/sliceOffset" } }, "uuid": { "name": "id", "in": "path", "schema": { "$ref": "#/components/schemas/uuid" }, "required": true, "description": "The primary identifier for the resource" } }, "requestBodies": { "contactPost": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/contact" }, { "type": "object", "required": [ "source" ], "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/sourceId" }, { "readOnly": false, "description": "The internal id of a source. \nCheck for the id of a [single source](#get-/sources/-id-) or of an item in [the collection](#get-/sources)." } ] }, "email": { "readOnly": false, "description": "", "example": "john@flexmail.be" } } } ] } } }, "required": true }, "contactPut": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/contact" }, { "required": [ "first_name", "name" ] } ] } } } }, "contactPatch": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contactPatch" } } } }, "contactImportPatch": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "queued" ] } } } } } }, "contactImportPost": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/uuidProvidedByClient" } } } } }, "required": true }, "contactImportRecordPost": { "required": true, "content": { "application/json": { "schema": { "title": "Contact records", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/contact" }, { "$ref": "#/components/schemas/contactImportRecordRelations" }, { "$ref": "#/components/schemas/contactImportRecordRelationsDeprecated" }, { "type": "object", "properties": { "email": { "readOnly": false } } } ] } } } } }, "interestSubscriptionPost": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "interest_id" ], "properties": { "interest_id": { "allOf": [ { "$ref": "#/components/schemas/uuid" }, { "description": "The Id of the interest that the contact is added to", "readOnly": false } ] } } } } }, "required": true }, "interestPost": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/interestPostInput" }, "example": { "name": "Programming", "visibility": "public", "label": "Programming", "description": "Let me know everything about programming!" } } }, "required": true }, "interestPatch": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/interestPatchInput" }, "example": { "name": "Web Development", "label": "Web Development", "description": "Everything about building websites and web applications" } } }, "required": true }, "interestTranslationsPut": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/interestTranslations" }, "example": { "label_translations": { "nl": "Programmeren", "en": "Programming" }, "description_translations": { "nl": "Ik wil alles weten over programmeren!", "en": "Let me know everything about programming!" } } } }, "required": true }, "optInPost": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/optIn" } } }, "required": true }, "preferenceSubscriptionPost": { "content": { "application/json": { "schema": { "type": "object", "required": [ "contact_id", "preference_id" ], "additionalProperties": false, "properties": { "contact_id": { "allOf": [ { "$ref": "#/components/schemas/internalIdForRelation" } ], "description": "The id of the contact to subscribe to the preference" }, "preference_id": { "allOf": [ { "$ref": "#/components/schemas/internalIdForRelation" } ], "description": "The id of the preference to subscribe the contact to" } } } } }, "required": true } }, "responses": { "accountContactLanguages": { "description": "The [contact languages](https://en.support.flexmail.eu/article/1111-about-languages) that are configured for the account.", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/accountContactLanguages" } } } }, "apiInfo": { "description": "Ok", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/apiInfo" } } } }, "contact": { "description": "A contact", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/contact" }, { "$ref": "#/components/schemas/contactLinks" } ] } } } }, "contacts": { "description": "The contacts collection", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/contacts" } } } }, "contactImport": { "description": "A contact import", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/contactImport" } } } }, "contactInterestLabels": { "description": "The interest label collection of a contact", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/contactInterestLabels" } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "contactImportStart": { "description": "A contact import", "headers": { "Location": { "schema": { "$ref": "#/components/schemas/headerLocation" }, "description": "The URI of the bulk import which can be used to monitor its status.", "required": true } }, "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/contactImportStart" } } } }, "contactPreferences": { "description": "The preference collection of a contact", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/contactPreferences" } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "contactSources": { "description": "The source collection of a contact", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/contactSources" } } } }, "customFields": { "description": "The custom fields collection", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/customFields" }, "examples": { "Collection in the default contact language": { "value": { "total": 3, "_embedded": { "item": [ { "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "type": "free_text", "placeholder": "firstname", "name": "Voornaam" }, { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "type": "multiple_choice", "placeholder": "interest", "name": "Interesse", "allows_multiple_values": true, "options": [ { "name": "Sport", "value": "sport" }, { "name": "Muziek", "value": "music" } ] }, { "id": "9c5b94b1-35ad-49bb-b118-8e8fc24abf80", "type": "date", "placeholder": "birth_date", "name": "Geboortedatum" } ] }, "_links": { "self": { "href": "/custom-fields" } } } }, "Collection localized in French (language=fr)": { "value": { "total": 3, "_embedded": { "item": [ { "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "type": "free_text", "placeholder": "firstname", "name": "Prénom" }, { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "type": "multiple_choice", "placeholder": "interest", "name": "Intérêt", "allows_multiple_values": true, "options": [ { "name": "Sport", "value": "sport" }, { "name": "Musique", "value": "music" } ] }, { "id": "9c5b94b1-35ad-49bb-b118-8e8fc24abf80", "type": "date", "placeholder": "birth_date", "name": "Date de naissance" } ] }, "_links": { "self": { "href": "/custom-fields?language=fr" } } } }, "Collection of free text fields (type=free_text)": { "value": { "total": 1, "_embedded": { "item": [ { "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "type": "free_text", "placeholder": "firstname", "name": "Voornaam" } ] }, "_links": { "self": { "href": "/custom-fields?type=free_text" } } } }, "Collection of numeric fields (type=numeric)": { "value": { "total": 1, "_embedded": { "item": [ { "id": "1d9f3c2a-6b47-4c8e-9a1b-2e3f4a5b6c7d", "type": "numeric", "placeholder": "loyalty_points", "name": "Getrouwheidspunten" } ] }, "_links": { "self": { "href": "/custom-fields?type=numeric" } } } }, "Collection of date fields (type=date)": { "value": { "total": 1, "_embedded": { "item": [ { "id": "9c5b94b1-35ad-49bb-b118-8e8fc24abf80", "type": "date", "placeholder": "birth_date", "name": "Geboortedatum" } ] }, "_links": { "self": { "href": "/custom-fields?type=date" } } } }, "Collection of multiple choice fields (type=multiple_choice)": { "value": { "total": 1, "_embedded": { "item": [ { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "type": "multiple_choice", "placeholder": "interest", "name": "Interesse", "allows_multiple_values": true, "options": [ { "name": "Sport", "value": "sport" }, { "name": "Muziek", "value": "music" } ] } ] }, "_links": { "self": { "href": "/custom-fields?type=multiple_choice" } } } }, "Collection of free text fields localized in French (type=free_text&language=fr)": { "value": { "total": 1, "_embedded": { "item": [ { "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "type": "free_text", "placeholder": "firstname", "name": "Prénom" } ] }, "_links": { "self": { "href": "/custom-fields?type=free_text&language=fr" } } } } } } } }, "interestLabels": { "description": "The interest label collection", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/interestLabels" } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "interestSubscriptions": { "description": "The interests of a contact", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/interestSubscriptions" } } } }, "interest": { "description": "A single interest", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/interest" }, { "$ref": "#/components/schemas/interestLinks" } ] } } } }, "interests": { "description": "The interest collection", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/interests" }, { "$ref": "#/components/schemas/interestsLinks" } ] } } } }, "interestTranslations": { "description": "The translations of an interest", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/interestTranslations" }, { "$ref": "#/components/schemas/interestTranslationsLinks" } ] } } } }, "optInForm": { "description": "An opt-in form", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/optInForm" }, { "$ref": "#/components/schemas/optInFormLinks" } ] } } } }, "optInForms": { "description": "A collection of all of the account's active opt-in forms.", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/optInForms" }, { "$ref": "#/components/schemas/optInFormsLinks" } ] }, "examples": { "collection of all opt-in forms": { "value": { "_embedded": { "item": [ { "id": 42, "name": "blog", "language": "nl", "created_at": "2023-07-06T20:20:39+00:00", "_links": { "self": { "href": "/opt-in-forms/42" } } } ] }, "_links": { "self": { "href": "/opt-in-forms" } } } }, "empty collection": { "value": { "_links": { "self": { "href": "/opt-in-forms" } } } } } } } }, "preference": { "description": "A preference", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/preference" }, { "$ref": "#/components/schemas/preferenceLinks" } ] } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "preferences": { "description": "The preference collection", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/preferences" } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "segments": { "description": "A collection of all the active segments", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/segments" }, { "$ref": "#/components/schemas/segmentsLinks" } ] }, "examples": { "collection of all segments": { "value": { "_embedded": { "item": [ { "id": "4ec225e2-6920-44d6-9729-b5990f1729e8", "parent_id": "556233f1-ec88-4913-b851-6abf7abe5d81", "name": "Dutch contacts segment", "number_of_contacts": 500, "last_campaign_date": "2022-12-01T11:29:33+01:00" }, { "id": "47c3883f-2842-43d3-80d0-f55ae12f4729", "name": "English contacts segment", "number_of_contacts": 112 } ] }, "_links": { "self": { "href": "/segments" } } } }, "empty collection": { "value": { "_links": { "self": { "href": "/segments" } } } } } } } }, "source": { "description": "A source", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/source" }, { "$ref": "#/components/schemas/sourceLinks" } ] } } } }, "sources": { "description": "The source collection", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/sources" } } } }, "webhook": { "description": "A webhook", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/webhook" }, { "$ref": "#/components/schemas/webhookLinks" } ] } } } }, "webhooks": { "description": "The webhooks collection", "content": { "application/hal+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/webhooks" }, { "$ref": "#/components/schemas/webhooksLinks" } ] } } } }, "webhookEvents": { "description": "The events that can be used to trigger webhooks. This list depends on the feature set of your Flexmail account.", "content": { "application/hal+json": { "schema": { "type": "object", "properties": { "events": { "description": "The event names that can trigger webhooks.", "type": "array", "items": { "type": "string" } }, "_links": { "required": [ "self" ], "type": "object", "properties": { "self": { "$ref": "#/components/schemas/relationLink" } } } }, "example": { "events": [ "contact.created", "contact.updated" ], "_links": { "self": { "href": "/webhook-events" } } } } } } }, "201": { "description": "Created", "headers": { "Location": { "$ref": "#/components/headers/location" } } }, "201_deprecation": { "description": "Created", "headers": { "Location": { "$ref": "#/components/headers/location" }, "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "201_uuid": { "description": "Created", "headers": { "Location": { "$ref": "#/components/headers/location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/genericResourceWithOnlyItsUuid" } } } }, "201_numericId": { "description": "Created", "headers": { "Location": { "$ref": "#/components/headers/location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/genericResourceWithOnlyItsNumericIdentifier" } } } }, "204": { "description": "No Content" }, "204_deprecation": { "description": "No Content", "headers": { "Deprecation": { "$ref": "#/components/headers/deprecation" } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "400": { "$ref": "#/components/examples/400" } } } } }, "400_ValidationError": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithValidationErrors" } ] } } } }, "400_InvalidQueryParameterError": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithInvalidQueryParameterError" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "401": { "$ref": "#/components/examples/401" } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "403": { "$ref": "#/components/examples/403" } } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "404": { "$ref": "#/components/examples/404" } } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "409": { "$ref": "#/components/examples/409" } } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "503": { "$ref": "#/components/examples/503" } } } } } }, "examples": { "400": { "value": { "title": "Bad Request", "type": "about:blank", "status": 400, "detail": "" } }, "401": { "value": { "title": "Unauthorized", "type": "about:blank", "status": 401, "detail": "" } }, "403": { "value": { "title": "Access to this resource is denied", "type": "\\/documentation\\/#access-error", "status": 403, "detail": "You are either not permitted to access this resource or it is not included in your current plan. Read more about Flexmail's plans on our website" } }, "404": { "value": { "title": "Not Found", "type": "about:blank", "status": 404, "detail": "" } }, "409": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "" } }, "503": { "value": { "title": "Service Unavailable", "type": "about:blank", "status": 503, "detail": "" } } }, "securitySchemes": { "personalAccessToken": { "type": "http", "scheme": "basic", "description": "Flexmail authenticates your API requests using the HTTP [Basic authentication](https://tools.ietf.org/html/rfc7617) scheme with your account ID as the _username_ and a personal access token as the _password_.\n\nPersonal access tokens can be managed in the Flexmail application via `Settings > API > Personal access tokens`\n\nExample of an authenticated API request using `curl`:\n```shell script\ncurl -u : -i -X GET https://api.flexmail.eu\n```\n " } } }, "paths": { "/": { "get": { "summary": "Retrieve API info", "description": "Retrieve general info about the API and the hypermedia links to start from.", "operationId": "getApiInfo", "tags": [ "API Root" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/apiInfo" }, "401": { "$ref": "#/components/responses/401" } } } }, "/contacts": { "get": { "summary": "List contacts", "description": "List (a slice of) the collection of all contacts. The collection can be filtered by an email address to find its corresponding contact, or by a single interest id to only return contacts actively subscribed to that interest. The `email` and `interest` filters cannot be combined.", "operationId": "listContacts", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/email" }, { "$ref": "#/components/parameters/interest" }, { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/contacts" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithInvalidQueryParameterError" } ] }, "examples": { "Multiple interest ids provided": { "value": { "title": "Invalid query parameter", "type": "https://api.flexmail.eu/documentation/#query-parameter-error", "status": 400, "detail": "Only one interest id is allowed", "parameter": "interest" } }, "Interest id is not a valid UUID": { "value": { "title": "Invalid query parameter", "type": "https://api.flexmail.eu/documentation/#query-parameter-error", "status": 400, "detail": "JsonSchema validation failed", "parameter": "interest" } }, "Interest does not exist": { "value": { "title": "Invalid query parameter", "type": "https://api.flexmail.eu/documentation/#query-parameter-error", "status": 400, "detail": "No interest exists with this id", "parameter": "interest" } }, "Both email and interest provided": { "value": { "title": "Invalid query parameter", "type": "https://api.flexmail.eu/documentation/#query-parameter-error", "status": 400, "detail": "The `email` and `interest` filters cannot be combined", "parameter": "interest" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "summary": "Create a contact", "description": "Create a contact", "operationId": "createContact", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/contactPost" }, "responses": { "201": { "$ref": "#/components/responses/201_numericId" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithValidationErrors" } ] }, "examples": { "Api problem": { "value": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "" } }, "Api Problem with Validation Errors": { "value": { "title": "Input validation failed", "type": "https://api.flexmail.eu/documentation/#validation-errors", "status": 400, "detail": "Some optional extra details about the error", "errors": [ { "pointer": "#/0/first_name", "message": "Invalid type integer, expected string", "constraint": "type" } ] } }, "The email address is blacklisted": { "value": { "type": "about:blank", "title": "Bad request", "status": 400, "detail": "The email address is blacklisted and can not be used to create a new contact. Instead, you should subscribe the contact via our double opt-in process (POST /opt-ins)." } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Contact with email address already exists": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "A contact with this email address already exists" } } } } } } } } }, "/contacts/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "summary": "Fetch a contact", "description": "Fetch a contact", "operationId": "getContact", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/contact" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "summary": "Update a contact", "description": "Update a contact (partially).", "operationId": "updateContact", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/contactPatch" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "put": { "summary": "Replace a contact", "description": "Completely replace the existing contact data, instead of [partially updating](#patch-/contacts/-id-) it.", "operationId": "replaceContact", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/contactPut" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/account-contact-languages": { "get": { "summary": "Fetch configured contact languages", "description": "Fetch the configured contact languages for the account. These are the languages in which you will communicate with your contacts and they are configured during the onboarding of the account. Languages are represented as a 2-letter code according to the [ISO 639-1 standard](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).\n\nFor more info about contact languages, read [the manual](https://en.support.flexmail.eu/article/1111-about-languages). ", "operationId": "getAccountContactLanguages", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/accountContactLanguages" }, "401": { "$ref": "#/components/responses/401" } } } }, "/contacts/{id}/interest-labels": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "deprecated": true, "summary": "List interest labels of a contact", "description": "List (a slice of) the collection of interest labels of a contact.", "operationId": "getContactInterestLabels", "tags": [ "Interest Labels" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/contactInterestLabels" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/contacts/{id}/interest-subscriptions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "summary": "List the interests of a contact", "description": "List the collection of all interests of the contact.", "operationId": "listInterestSubscriptions", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/interestSubscriptions" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "post": { "summary": "Add a contact to an interest", "description": "Add a contact to an interest. If the contact itself has unsubscribed from this interest then this operation is refused with a `HTTP 403` response.", "operationId": "createInterestSubscription", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/interestSubscriptionPost" }, "responses": { "201": { "$ref": "#/components/responses/201" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contacts/{id}/interest-subscriptions/{interest_id}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "in": "path", "name": "interest_id", "schema": { "$ref": "#/components/schemas/uuid" }, "required": true, "description": "The interest id" } ], "delete": { "summary": "Remove a contact from an interest", "description": "Remove a contact from an interest.", "operationId": "deleteInterestSubscription", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } } } }, "/contacts/{id}/preferences": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "deprecated": true, "summary": "List preferences of a contact", "description": "List (a slice of) the collection of preferences of a contact.", "operationId": "getContactPreferences", "tags": [ "Preferences" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/contactPreferences" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/contacts/{id}/sources": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "summary": "List sources of a contact", "description": "List (a slice of) the collection of sources of a contact.", "operationId": "getContactSources", "tags": [ "Sources" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/contactSources" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } } } }, "/contacts/{id}/unsubscribe": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "summary": "Unsubscribe a contact", "description": "Unsubscribe a contact from your communication. If a contact is unsubscribed, it can only be [resubscribed via opt-in](#post-/opt-ins).", "operationId": "unsubscribeContact", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contacts/imports": { "post": { "summary": "Create a bulk import of contacts", "description": "Create a bulk import of contacts which can be used to create or update multiple contacts in your account at once. Before the bulk import can be [started](#post-/contacts/imports/-id-/start), at least one record of contact data needs to be [added](#post-/contacts/imports/-id-/records) to it.", "operationId": "createImport", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/contactImportPost" }, "responses": { "201": { "$ref": "#/components/responses/201_uuid" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contacts/imports/{id}": { "parameters": [ { "$ref": "#/components/parameters/uuid" } ], "get": { "summary": "Fetch a bulk import of contacts", "description": "Fetch a bulk import of contacts when you [started](#post-/contacts/imports/-id-/start) it to get to know its status and/or result.", "operationId": "getContactImport", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/contactImport" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "deprecated": true, "summary": "Update a bulk import of contacts", "description": "Update the status of a bulk import of contacts to indicate it should be started.\n\n⚠️ **Deprecated**, use [this](#post-/contacts/imports/-id-/start) better alternative instead.", "operationId": "updateContactImport", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/contactImportPatch" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contacts/imports/{id}/records": { "parameters": [ { "$ref": "#/components/parameters/uuid" } ], "post": { "summary": "Add records to a bulk import of contacts", "description": "Add records of contact data to a bulk import of contacts. After the necessary records are added, the bulk import can be [started](#post-/contacts/imports/-id-/start). \n\nWe advise to keep the number of contact records in 1 request below 100.000 records. If you want to import even more records, you can split them into separate requests to this endpoint.", "operationId": "addContactImportRecords", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/contactImportRecordPost" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contacts/imports/{id}/start": { "parameters": [ { "$ref": "#/components/parameters/uuid" } ], "post": { "summary": "Start a bulk import of contacts", "description": "Start a bulk import of contacts. Only 1 concurrent bulk import is allowed to run so if you try to start another one, you will get a `409` response.\n\n⚠️ Please note that processing a bulk import can take quite some time, depending on the amount and the complexity of records that it contains. While we do send an email notification when the processing is done, you can also [check the status](#get-/contacts/imports/-id-).", "operationId": "startContactImport", "tags": [ "Contacts" ], "security": [ { "personalAccessToken": [] } ], "responses": { "202": { "$ref": "#/components/responses/contactImportStart" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contact-preference-subscriptions": { "post": { "deprecated": true, "summary": "Create a preference subscription", "description": "Subscribe a contact to a preference.", "operationId": "addPreferenceSubscription", "tags": [ "Preferences" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/preferenceSubscriptionPost" }, "responses": { "201": { "$ref": "#/components/responses/201_deprecation" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/contact-preference-subscriptions/{id}": { "parameters": [ { "$ref": "#/components/parameters/compoundId" } ], "delete": { "deprecated": true, "summary": "Delete a preference subscription", "description": "Unsubscribe a contact from a preference.", "operationId": "deletePreferenceSubscription", "tags": [ "Preferences" ], "security": [ { "personalAccessToken": [] } ], "responses": { "204": { "$ref": "#/components/responses/204_deprecation" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" } } } }, "/custom-fields": { "get": { "summary": "List custom fields", "description": "List the collection of all available custom fields.", "operationId": "listCustomFields", "tags": [ "Custom Fields" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/customFieldType" }, { "$ref": "#/components/parameters/contactLanguage" } ], "responses": { "200": { "$ref": "#/components/responses/customFields" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" } } } }, "/interests": { "get": { "summary": "List interests", "description": "List (a slice of) the collection of all available interests.", "operationId": "listInterests", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/interestName" }, { "$ref": "#/components/parameters/interestVisibility" }, { "$ref": "#/components/parameters/interestOrderBy" }, { "$ref": "#/components/parameters/orderDirection" }, { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/interests" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" } } }, "post": { "summary": "Create an interest", "description": "Create an interest for the account.", "operationId": "createInterest", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/interestPost" }, "responses": { "201": { "$ref": "#/components/responses/201_uuid" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithValidationErrors" } ] }, "examples": { "Api problem": { "value": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "" } }, "Api Problem with Validation Errors": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/name", "message": "The property name is required", "constraint": "required" } ] } }, "Name too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/name", "message": "Must be at most 50 characters long", "constraint": "maxLength" } ] } }, "Name contains a comma": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/name", "message": "Does not match the regex pattern ^[^,]*$", "constraint": "pattern" } ] } }, "Invalid visibility value": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/visibility", "message": "Does not have a value in the enumeration [\"public\",\"private\"]", "constraint": "enum" } ] } }, "Label too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/label", "message": "Must be at most 50 characters long", "constraint": "maxLength" } ] } }, "Description too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/description", "message": "Must be at most 100 characters long", "constraint": "maxLength" } ] } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Access denied": { "value": { "title": "Access to this resource is denied", "type": "/documentation/#access-error", "status": 403, "detail": "You are either not permitted to access this resource or it is not included in your current plan. Read more about Flexmail's plans on our website" } }, "Interest limit reached": { "value": { "title": "Access to this resource is denied", "type": "/documentation/#access-error", "status": 403, "detail": "The maximum number of interests for this account has been reached" } }, "Private interest not allowed": { "value": { "title": "Feature not available on your current plan", "type": "/documentation/#access-error", "status": 403, "detail": "Private interests require a Pro plan or higher. Upgrade your plan to use this feature.", "upgrade_url": "https://flexmail.be/en/pricing/" } } } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Duplicate interest name": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "An interest with this name already exists" } } } } } } } } }, "/interests/{id}": { "parameters": [ { "$ref": "#/components/parameters/uuid" } ], "get": { "summary": "Fetch an interest", "description": "Fetch a single interest by its identifier.", "operationId": "getInterest", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/interest" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "summary": "Partially update an interest", "description": "Only the provided fields will be updated, all other fields retain their current values.", "operationId": "updateInterest", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/interestPatch" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithValidationErrors" } ] }, "examples": { "Api problem": { "value": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "" } }, "Api Problem with Validation Errors": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/name", "message": "The property name is required", "constraint": "required" } ] } }, "Name too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/name", "message": "Must be at most 50 characters long", "constraint": "maxLength" } ] } }, "Name contains a comma": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/name", "message": "Does not match the regex pattern ^[^,]*$", "constraint": "pattern" } ] } }, "Invalid visibility value": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/visibility", "message": "Does not have a value in the enumeration [\"public\",\"private\"]", "constraint": "enum" } ] } }, "Label too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/label", "message": "Must be at most 50 characters long", "constraint": "maxLength" } ] } }, "Description too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/description", "message": "Must be at most 100 characters long", "constraint": "maxLength" } ] } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Access denied": { "value": { "title": "Access to this resource is denied", "type": "/documentation/#access-error", "status": 403, "detail": "You are either not permitted to access this resource or it is not included in your current plan. Read more about Flexmail's plans on our website" } }, "Private interest not allowed": { "value": { "title": "Feature not available on your current plan", "type": "/documentation/#access-error", "status": 403, "detail": "Private interests require a Pro plan or higher. Upgrade your plan to use this feature.", "upgrade_url": "https://flexmail.be/en/pricing/" } } } } } }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Duplicate interest name": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "An interest with this name already exists" } } } } } } } }, "delete": { "summary": "Delete an interest", "description": "Deletion of an interest is rejected when contacts are subscribed to it, it is referenced by opt-in forms, or is used to segment contacts.", "operationId": "deleteInterest", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Access denied": { "value": { "title": "Access to this resource is denied", "type": "/documentation/#access-error", "status": 403, "detail": "You are either not permitted to access this resource or it is not included in your current plan. Read more about Flexmail's plans on our website" } } } } } }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Interest in use by opt-in forms": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "The interest cannot be deleted because it is referenced by one or more opt-in forms" } }, "Interest in use by segment conditions": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "The interest cannot be deleted because it is used to segment contacts" } }, "Interest has active subscriptions": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "The interest cannot be deleted because one or more contacts are subscribed to it" } } } } } } } } }, "/interests/{id}/translations": { "parameters": [ { "$ref": "#/components/parameters/uuid" } ], "get": { "summary": "Fetch interest translations", "description": "Fetch the label and description translations for an interest. Translations are keyed by the language codes of the [account's configured contact languages](#get-/account-contact-languages).", "operationId": "getInterestTranslations", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/interestTranslations" }, "401": { "$ref": "#/components/responses/401" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Interest not found": { "value": { "title": "Not Found", "type": "about:blank", "status": 404, "detail": "" } }, "Single contact language": { "value": { "title": "Not Found", "type": "about:blank", "status": 404, "detail": "Translations are not available because the account has only one configured contact language" } } } } } } } }, "put": { "summary": "Replace interest translations", "description": "Replace all label and description translations for an interest. Translations are keyed by the language codes of the [account's configured contact languages](#get-/account-contact-languages).", "operationId": "replaceInterestTranslations", "tags": [ "Interests" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/interestTranslationsPut" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "$ref": "#/components/schemas/apiProblemWithValidationErrors" } ] }, "examples": { "Missing translation language": { "value": { "title": "Bad request", "type": "about:blank", "status": 400, "detail": "Translations for the following required languages are missing: \"fr\"" } }, "Redundant translation language": { "value": { "title": "Bad request", "type": "about:blank", "status": 400, "detail": "Translations for the following unconfigured languages were provided: \"it\"" } }, "Label translations required": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/label_translations", "message": "The property label_translations is required", "constraint": "required" } ] } }, "Description translations required": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/description_translations", "message": "The property description_translations is required", "constraint": "required" } ] } }, "Label translation too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/label_translations/nl", "message": "The value should be no longer than 50 characters", "constraint": "maxLength" } ] } }, "Description translation too long": { "value": { "title": "Input validation failed", "type": "/documentation/#validation-errors", "status": 400, "detail": "", "errors": [ { "pointer": "#/description_translations/nl", "message": "The value should be no longer than 100 characters", "constraint": "maxLength" } ] } } } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/apiProblem" }, "examples": { "Interest not found": { "value": { "title": "Not Found", "type": "about:blank", "status": 404, "detail": "" } }, "Single contact language": { "value": { "title": "Not Found", "type": "about:blank", "status": 404, "detail": "Translations are not available because the account has only one configured contact language" } } } } } } } } }, "/interest-labels": { "get": { "deprecated": true, "summary": "List interest labels", "description": "List (a slice of) the collection of all interest labels.", "operationId": "listInterestLabels", "tags": [ "Interest Labels" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/interestLabels" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/opt-ins": { "post": { "summary": "Submit an opt-in", "description": "Initiate the double opt-in process by submitting an optin for a specified email address. A confirmation mail containing instructions on how to confirm the opt-in will be sent to this address. An opt-in will be automatically deleted if is not confirmed within 24 hours and in that case the opt-in will need to be resubmitted.\n\nIt is also required to provide the ID of an [active opt-in form](#get-/opt-in-forms) of your account in the opt-in submission. The email configuration of this form will be used to send the confirmation mail. Please note that this mail can be branded but it is not possible to customize its actual content or anything else that is not included the form's email configuration.\n\nOptionally you can also provide values for other contact fields. If the opt-in is confirmed, this data will be used for the created contact.\n\nIf the opt-in is eventually confirmed it will result in a new contact and trigger the [`opt-in.confirmed`](webhooks#post-optInConfirmed) and [`contact.created`](webhooks#post-contactCreated) webhooks.\n\nSubmitting an opt-in for an email address that belongs to an existing contact or for which there already is a pending opt-in is not allowed and will result in a `409` error response.", "operationId": "submitOptIn", "tags": [ "Opt-in" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "$ref": "#/components/requestBodies/optInPost" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "title": "API Problem with Relation Link", "allOf": [ { "$ref": "#/components/schemas/apiProblem" }, { "type": "object", "title": "relationLinks", "properties": { "_links": { "type": "object", "required": [ "conflict" ], "properties": { "conflict": { "$ref": "#/components/schemas/contactRelationLink" } }, "readOnly": true } } } ] }, "examples": { "Opt-in for email address already exists": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "An opt-in for this email address already exists" } }, "Contact with email address already exists": { "value": { "title": "Conflict", "type": "about:blank", "status": 409, "detail": "A contact with this email address already exists", "_links": { "conflict": { "href": "/contacts/42" } } } } } } } }, "503": { "$ref": "#/components/responses/503" } } } }, "/opt-in-forms": { "get": { "summary": "List opt-in forms", "description": "List the collection of all of the account's active opt-in forms.", "operationId": "listOptInForms", "tags": [ "Opt-in" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/optInForms" }, "401": { "$ref": "#/components/responses/401" } } } }, "/opt-in-forms/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "summary": "Fetch an opt-in form", "description": "Fetch the details of an opt-in form.\nThe language of the form will be used as the communication language for the confirmation mail that is sent when an opt-in is submitted for this form. The other details of that mail are determined by the form's email configuration.\n\nAn opt-in form requires an email address but can also contain other contact fields if you want to collect extra contact data during the subscription.\n\nUp to 5 interest can be configured and the contacts that are subscribed via this form will be automatically subscribed to them.", "operationId": "getOptInForm", "tags": [ "Opt-in" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/optInForm" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } } } }, "/preferences": { "get": { "deprecated": true, "summary": "List preferences", "description": "List (a slice of) the collection of all preferences.", "operationId": "listPreferences", "tags": [ "Preferences" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/preferences" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/segments": { "get": { "summary": "List segments", "description": "List the collection of all of the account's valid and active segments.", "tags": [ "Segments" ], "responses": { "200": { "$ref": "#/components/responses/segments" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } }, "operationId": "listSegments" } }, "/sources": { "get": { "summary": "List sources", "description": "List (a slice of) the collection of all available sources.", "operationId": "listSources", "tags": [ "Sources" ], "security": [ { "personalAccessToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/sliceLimit" }, { "$ref": "#/components/parameters/sliceOffset" } ], "responses": { "200": { "$ref": "#/components/responses/sources" }, "400": { "$ref": "#/components/responses/400_InvalidQueryParameterError" }, "401": { "$ref": "#/components/responses/401" } } } }, "/sources/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "summary": "Fetch a source", "description": "Fetch a source", "operationId": "getSource", "tags": [ "Sources" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/source" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } } } }, "/webhooks": { "get": { "summary": "List webhooks", "description": "List the collection of all webhooks.", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/webhooks" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "summary": "Create a webhook", "description": "Create a webhook that subscribes to an event. Use [GET /webhook-events](#get-/webhook-events) to find out to which events you can subscribe. Maximum 10 webhooks can be created per event.\n\nDuring the creation of the webhook we will verify your identity. Read [here](webhooks#overview--security) how this is handled. If this verification fails we will not create the webhook and inform you about this with a HTTP `400` response code.", "operationId": "createWebhook", "tags": [ "Webhooks" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "event_name": { "description": "The name of the event that triggers the webhook.", "type": "string", "example": "contact.created" }, "target_url": { "description": "The target URL that will receive the HTTP callback when the webhook is triggered. Must use HTTPS.", "type": "string", "format": "uri", "minLength": 1, "maxLength": 255, "example": "https://example.org/webhook-receiver" }, "verification_token": { "$ref": "#/components/schemas/webhookVerificationToken" } }, "required": [ "event_name", "target_url" ] } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/201_uuid" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" } } } }, "/webhooks/{id}": { "parameters": [ { "$ref": "#/components/parameters/uuid" } ], "patch": { "summary": "Update a webhook", "description": "Change the target URL of a webhook. This requires you to verify your identity again.", "operationId": "updateWebhook", "tags": [ "Webhooks" ], "security": [ { "personalAccessToken": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "target_url" ], "additionalProperties": false, "properties": { "target_url": { "description": "The target URL that will receive the HTTP callback when the webhook is triggered. Must use HTTPS.", "type": "string", "format": "uri", "minLength": 1, "maxLength": 255, "example": "https://example.org/webhook-receiver" } } } } }, "required": true }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400_ValidationError" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" } } }, "get": { "summary": "Fetch a webhook", "description": "Fetch a webhook", "operationId": "getWebhook", "tags": [ "Webhooks" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/webhook" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "delete": { "summary": "Remove a webhook", "description": "Delete a webhook by its ID", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/webhook-events": { "get": { "summary": "List webhook events", "description": "List all events that can trigger webhooks for your account. The available events depend on your current account plan.\n\nMore information about webhook events can be found [here](webhooks#overview--events)", "operationId": "listWebhookEvents", "tags": [ "Webhooks" ], "security": [ { "personalAccessToken": [] } ], "responses": { "200": { "$ref": "#/components/responses/webhookEvents" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } } } }