Terminology

These are the definitions for the most basic terms used in the Apsis API.

API key

A unique identifier that needs to be included in each API call. It identifies the caller of the API and defines what data the caller has the right to access. You create and manage the API keys via the Apsis web GUI. Using HTTPS only is the recommended way to secure your communication with the API, this is done using 8443 as port. One account can have multiple keys. It is important to keep the API key secure and to change it if you suspect any leak of the key.

Bounces

A bounced email address is an address that did not reach its intended recipient because of one of many possible reasons. Most often, a bounce occurs when an email address is obsolete or when a recipient's inbox is full. Bouces also occur when the receiving ISP has technical issues. For most bounces, APSIS receives error messages from ISP's with information about the reason. NB! If an email send-out returns Out of office messages, these should not be considered bounces but rather normal responses to emails sent.

Demographic Data

Meta data related to the demography of a subscriber, for example the address, mobile phone number or gender of the person. A subscriber can have up to 100 demographic fields and each field can host up to 500 characters of text. The demographic data is connected on a subscriber level, meaning that you cannot have different demographic data on different mailing lists for the same subscriber.

Event

Apsis Event is a feature to manage an event flow from invitations, reminders to registrations and check-ins. Events should be set up in the graphical user interface, and the REST API offers methods to retrieve events and also statuses of event participants.

ExternalId

This field is used to add an identifier from an external system into APSIS Pro that can later be retrieved via various API methods like GetClicks or GetMailinglistSubscribers. The type of the field is string and it holds a maximum of 50 characters. NB! Email is still the unique key per APSIS Pro account, even though ExternalId is used.

Filter

The filter functionality in APSIS Pro is used to select a sub-group of subscribers (e.g. all subscribers on a list where "Gender" equals "Female" or similar). These filters are set-up from within the graphical user interface and can for example be based on demographic data (see above), various time stamps, and on opens or clicks (or non-opens and non-clicks) in newsletters. These types can also be used in combination to narrow down the selection according to your needs (e.g. e.g. all subscribers on a list where "Gender" equals "Female" who where created on the APSIS Pro account this year and who did not open the previous newsletter). The filters can currently not be created using the API.

Folder

In APSIS Pro, folder structures can be created to manage content (newsletter, surveys etc.), lists or reports. The folders cannot be created using the API, rather they are created from within APSIS Pro. However, folders can be retrieved through the API.

Format

In the context of an API response this defines in what the format of the response will be, valid values are XML and JSON.

In the context of subscribers, format means the preferred newsletter format to receive, either Text or HTML.

JSON

JSON stands for JavaScript Object Notation and it is a serialized JavaScript object. Basically it is a text in a certain format that allows definitions of key-value pairs, objects and arrays. JSON is easy to parse in most programming language and has become a de facto standard in REST APIs. See http://json.org/ for more details on JSON syntax and how to parse JSON.

Multi-part MIME

Multi-part MIME refers to sending both an HTML and a TEXT part of an email message in a single email, where the content-type header of the email contains references both to plain text and to HTML. When a subscriber's email client receives a multipart message, it accepts the HTML version if it can render HTML, otherwise it presents the plain text version.

Mailing list

A mailing list contains a list of subscribers, a sender name, sender email address, a description and a character set. When sending a newsletter, you will need to select a mailing list to send to.

Newsletter

Any kind of email (newsletter, email campaign, event invitation email, etc.) that can be sent out to subscribers on a mailing list. A newsletter exists in either a plain text version or a HTML formatted version, or preferably both (see Multi-part MIME) since which version is shown to the subscriber depends on the capabilities and settings of their mail client.

Opt out all

Opt out all is when a subscriber opts out (opts not to receive more emails) from an APSIS Pro account (i.e most often an APSIS customer). A subscriber's email address that ends up on the "Opt out all" list in APSIS Pro cannot be added to the account again until a) the email address has been deleted from the Opt out all list or b) the email address re-subscribes to the account through an APSIS Pro generated subscription form (form builder available in the APSIS Pro GUI).

Opt out list

Opt out list is when a subscriber opts out (opts not to receive more emails) from a specific list in APSIS Pro. A subscriber's email address that ends up on the "Opt out list" for a certain list in APSIS Pro cannot be added to that list again until a) the email address has been deleted from that "Opt out list" list or b) the email address re-subscribes to that list account through an APSIS Pro generated subscription form (form builder available in the APSIS Pro GUI). Opting out from a list does mean you may still be a subscriber to another list on that same account.

Paging

A way to reduce a large result set in an API response into manageable chunks. The thought is to be able to view and handle one page of data at a time. For example, instead of returning all newsletters the API can return only ten at a time, making it easier to handle for the API user as well as reducing the load on the API server. If you need to retrieve all data then you should look at using queued methods.

Queued methods

Some API calls are quite resource intensive and to reduce the load on the system certain API calls are placed in a queue to allow processing in a more controlled fashion. This reduces the overall the response time of the API by not waiting for the API to perform a complicated task before an answer is returned. Instead the API returns an URL that needs to be polled to return the result of the original API request. Another reason is to reduce the risk of timeouts for very big operations.

RecipientId

The RecipientId is the unique Id used for a recipient on an account. Two recipients on one account can therefore not have the same RecipientId. Formerly called SubscriberId.

REST

REST stands for REpresentational State Transfer and is a way to build an API using the HTTP standard. The main advantages of REST style APIs (also refered to as RESTful) are that they are easy to use, easy to test and have good performance.

SMS

The API allows you to send two types of SMS messages, transactional SMS to one recipient (using the Send method from the SMS resource section) or send SMS to a list of recipients (using the SendNewsletter method in the Newsletter resource section).

Subscriber

A subscriber is the recipient of an email, a survey, an event invitation etc. A subscriber holds information like email address (required), name, phone number and other contact-related data like gender, customer type, city etc. (called demographic data in APSIS Pro).

SubscriberId

The SubscriberId is the unique Id used for a subscriber on an account. Two subscribers on an account can therefore not have the same SubscriberId. Being renamed to RecipientId.

Subscription

A subscription is when a subscriber subscribes to a mailing list. A subscriber can subscribe to one or many mailing lists.

TransactionalEmail

A transactional email is an email that is sent to one recipient based on any form of transaction. A transaction can be a purchase (order confirmation or receipt), a password reset email, abandoned cart email, shipping information, expiration emails (agreements, discount codes) etc. The transactional email feature of APSIS Pro is a paid add-on, please contact your Account Manager or send an email to info@apsis.com to learn more.

WebVersionLink

WebVersionLink or Web Version URL is a URL that is automatically generated when an email is sent via APSIS Pro. Adding the dynamic parameter ##WebVersion## in an APSIS Pro email, a subscriber-unique URL is created when the email is built and sent out from APSIS Pro. This is often placed in the top section of the email. They should also in the text version of emails to provide standard tracking for subscribers that click this URL in text-based versions of emails.