Terminology

The following page contains the definitions for the most basic terms used in the APSIS API.

API key

An API Key is a unique identifier that is required in each API call. It identifies the caller of the API and defines what data the caller has the right to access. One account can have multiple keys, and you can create and manage them through the APSIS web GUI. Using HTTPS only is the recommended way to secure your communication with the API, and this is done by using 8443 and 443 as port. 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 for various reasons. Most commonly, a bounce occurs when an email address is inactive, non-existent or when a recipient's inbox is full. Bounces might also occur when the receiving ISP has technical issues. For most bounces, APSIS receives error messages from ISPs with information about the cause.

Please note: 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

Demographic data is metadata related to the demography of a subscriber, such as the address, cell phone number or gender of a 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. In other words: you cannot have different demographic data on different mailing lists for the same subscriber.

Event

APSIS Event is a feature that manages an event flow. Events should be set up in the graphical user interface, and the REST API offers methods to retrieve events and statuses of event participants.

ExternalId

ExternalId is a field that is used to add an identifier from an external system into APSIS Pro that can later be retrieved via various API methods, such as GetClicks or GetMailinglistSubscribers. The field type is string and it can hold a maximum of 50 characters.

Please note: Email is still the unique key per APSIS Pro account, even if 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 in the graphical user interface and can, for example, be based on demographic data, time stamps, and newsletter activities. These types of filters can also be combined to narrow down the selection to suit your needs (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. These folders can be created in APSIS Pro or APSIS API.

Format

In the context of an API response, this defines the format of the response. Valid values are XML and JSON.

In the context of subscribers, format is the preferred newsletter format to receive. This can be either Text or HTML.

JSON

JSON stands for JavaScript Object Notation and it is a serialised JavaScript object. 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 languages, and has become a standard in REST APIs. Visit 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 to both plain text and 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. This includes a sender name, sender email address, a description, and a character set. When sending a newsletter, you will need to select a mailing list.

Newsletter

A newsletter is any kind of email that can be sent to subscribers on a mailing list. A newsletter exists either as a plain text version or as an HTML formatted version. As email client capabilities may vary, a newsletter should preferably have both (see Multi-part MIME).

Opt out all

Opt out all is when a subscriber chooses not to continue to receive emails from a particular APSIS Pro account. 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 either the email address has been deleted from the Opt out all list or 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 chooses not to continue to receive 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 either the email address has been deleted from that "Opt out list" list or 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

Paging is a method of reducing 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. This makes it easier for the API user to handle the result and it reduces the load on the API server. You should use queued methods if you need to retrieve all data.

Queued methods

Some API calls are quite resource intensive. To reduce the load on the system, these calls are placed in a queue. This enables a more controlled processing of the calls and reduces the API's overall response time by not having to wait for the API to perform a complicated task before an answer is returned. With queued methods, the API returns a URL that needs to be polled in order 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 (formerly called SubscriberId) is the unique Id used for a recipient on an account. This means that two recipients on one account cannot have the same RecipientId.

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 referred to as RESTful) are that they are easy to use, easy to test and perform well.

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 or an event invitation. A subscriber contains information such as email address (required), name, phone number, and other contact-related demographic data (gender, customer type, city etc).

Subscription

A subscription is when a person (subscriber) chooses to subscribe 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. Contact your Account Manager or send an email to customerservice.apsis@efficy.com for more information.

WebVersionLink

WebVersionLink (also called Web Version URL) is a URL that is automatically generated when an email is sent through APSIS Pro. If you add 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. In text version emails, the WebVersionLink provides standard tracking for subscribers that click on the URL in text-based versions of emails.