Mailrelay API Reference

Import a new file

POST https://{account}/api/v1/imports

Authentication

Requires an API key sent in the X-AUTH-TOKEN header.

This function should be used when you need to import a large number of subscribers and adding then individually is very slow.

This function expects you to provide importfieldsattributes which is an array indicating what each column in your file represents. If you have the following CSV where the first column is an email, the second is the name of the subscriber and the third is the value for a custom field with id 4:

[email protected],John Doe,my custom value
[email protected],Lisa Doe,another custom value

The following value for importfieldsattributes should be sent:

[
  {
    column: 0,
    field: 'email'
  },
  {
    column: 1,
    field: 'name'
  },
  {
    column: 2,
    field: 'custom_field_4'
  }
]

If you specify a callback URL, we will send a POST request right after the import is processed. It will contain a JSON with the type of the callback and the ID of the import.

You can use the following command to simulate a callback request:

curl --request POST \
  --url https://your-callback-domain.com/callback-url \
  --header 'content-type: application/json' \
  --data '{"type":"import_finished","id":1}'

Parameters

NameTypeRequiredDescription
file Yes
existing_subscribers string No If a subscriber already exists, what should we do?
callback_url string No A URL that will be called when the import process has finished. A POST request will be sent to this URL with a JSON payload containing the ID of the import.
import_fields_attributes array No Import fields attributes
group_ids array No Group ids

Responses

StatusDescription
201 Success
400 The request is invalid. Check if the field names in the request and the request data is valid.
422 A validation error occurred. Check the response body for more information.
401 The API key wasn't sent, is invalid or has expired
403 The API key or its user doesn't have permission to use this endpoint, or the request comes from an IP address the key doesn't allow.
429 Too many requests. You have exceeded the rate limit, wait and try again later.
500 An internal error happened. Try again later.

Response fields

NameTypeDescription
id integer ID
name string Name
number_of_records integer Number of records
status string Status
finished_at string Finished at
created_at string Created at
updated_at string Updated at
file
import_fields array Import fields