Working with the rapidmail API

Features

With the rapidmail API 3.0, you have access to the following functionalities

• Mailings
  • Send mailings from a zip file
  • List mailings
  • Get details of a single mailing
  • Get mailing statistics
• Manage recipient lists
• Manage recipients
• Manage your blacklist
• Manage API users for your account

Getting access

To access the API you need a rapidmail account. You can create an account here. Then you need to create an API user. To do this, log into your rapidmail account, and access the API user management interface via Settings › API

Throttling

Our API is throttled by request volume. You can do a maximum of 10 requests per second. If you exceed your request limit, a Statuscode 503 response will be returned.

Accessing the API

API client library

We provide a user friendly API client for the PHP programming language. The API client itself, documentation and examples can be found within our GitHub repository.

Alternative (without client library): Sending manual HTTP requests

The rapidmail API 3.0 supports HTTP Basic Authentication. Please see the following example on how to use curl to make an authenticated request:

                
                    curl --request GET \
                    --url 'https://apiv3.emailsys.net/mailings' \
                    --user 'apiusername:apipassword'
                
            

API structure

Our API uses a RESTful architecture throughout. Most of the API is self-describing (see HATEOAS) using HAL where appropriate.

Data format

Our API uses the JSON format. Accept and Content-Type headers should always be "application/json" unless specified otherwise in the respective services' documentation. Related links (e.g. for pagination) will be provided using HAL. Please see the following sample response for a paginated recipient list.

                
                    {
                        "_links": {
                            "self": {
                                "href": "https://apiv3.emailsys.net/recipients?recipientlist_id=1&page=1"
                            },
                            "first": {
                                "href": "https://apiv3.emailsys.net/recipients?recipientlist_id=1"
                            },
                            "last": {
                                "href": "https://apiv3.emailsys.net/recipients?recipientlist_id=1&page=1"
                            }
                        },
                        "_embedded": {
                            "recipients": [
                                {
                                    "id": "1",
                                    "email": "michael.j.fox@example.net",
                                    "firstname": "Michael J.",
                                    "lastname": "Fox",
                                    "gender": "male",
                                    "title": null,
                                    "zip": "",
                                    "birthdate": null,
                                    "extra1": "testdata-extra1",
                                    "extra2": "testdata-extra2",
                                    "extra3": "testdata-extra3",
                                    "extra4": "testdata-extra4",
                                    "extra5": "testdata-extra5",
                                    "extra6": "testdata-extra6",
                                    "extra7": "",
                                    "extra8": "",
                                    "extra9": "",
                                    "extra10": "i",
                                    "mailtype": "html",
                                    "foreign_id": null,
                                    "created_ip": "127.0.0.1",
                                    "created_host": null,
                                    "created": "2018-01-01 12:52:45",
                                    "updated": "2018-01-02 11:09:43",
                                    "_links": {
                                        "self": {
                                            "href": "https://apiv3.emailsys.net/recipients/1"
                                        }
                                    }
                                }
                            }
                        }
                    }
                
            

SSL

Our API is HTTPS-Only, it is not possible to access it via HTTP. Please make sure your client library supports HTTPS.