NAV Navbar
cURL json

Authentication

https://api.coresender.com expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer api_key

Domains

List domains

Request:

GET https://api.coresender.com/v1/domains/
curl --request GET "https://api.coresender.com/v1/domains/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": [
    {
      "name": "example.com",
      "created_at": "2019-05-27T12:43:29.599267Z",
      "dkim": {
        "host_name": "coresender._domainkey.example.com",
        "text": "v=DKIM1; k=rsa; p=..."
      }
    }
  ]
}

List all sending domains.

HTTP Request

GET https://api.coresender.com/v1/domains/

Response data

field type description
data[].name string Domain name
data[].dkim.host_name string DNS record name
data[].dkim.text string DNS record value

Get domain info

Request:

GET https://api.coresender.com/v1/domains/:name/
curl --request GET "https://api.coresender.com/v1/domains/google.email/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": {
    "name": "example.com",
    "dkim": {
      "host_name": "coresender._domainkey.example.com",
      "text": "v=DKIM1; k=rsa; p=..."
    }
  }
}

Get sending domain data.

HTTP Request

GET https://api.coresender.com/v1/domains/:name/

Response data

field type description
data.name string Domain name
data.dkim.host_name string DNS record name
data.dkim.text string DNS record value

Add domain

Request:

POST https://api.coresender.com/v1/domains/
curl --request POST "https://api.coresender.com/v1/domains/" \
  --header "Authorization: Bearer {{api_key}}" \
  --header "Content-Type: application/json" \
  --data "{
    \"name\": \"example.com\"
  }"
{
  "name": "example.com",  // The domain name.
}

Response:

{
  "status": "success",
  "data": {
    "name": "example.com",
    "dkim": {
      "host_name": "coresender._domainkey.example.com",
      "text": "v=DKIM1; k=rsa; p=..."
    }
  }
}

Add a new sending domain. The returned DKIM record needs to be set in the DNS of the domain before any message is sent.

HTTP Request

POST https://api.coresender.com/v1/domains/

Request data

field type required
name string true

Response data

field type description
data.name string Domain name
data.dkim.host_name string DNS record name
data.dkim.text string DNS record value

Delete domain

Request:

DELETE https://api.coresender.com/v1/domains/:name/
curl --request DELETE "https://api.coresender.com/v1/domains/google.email/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": null
}

Delete a sending domain.

HTTP Request

DELETE https://api.coresender.com/v1/domains/:name/

IPs

Provision IP

Request:

POST https://api.coresender.com/v1/ips/
curl --request POST "https://api.coresender.com/v1/ips/" \
  --header "Authorization: Bearer {{api_key}}" \
  --header "Content-Type: application/json" \
  --data "{
    \"pool\": \"pool1\"
  }"
{
  "pool": "pool1"  // IP pool name.
}

Response:

{
  "status": "success",
  "data": {
    "address": "127.0.0.1",
    "pool": "pool1",
    "created_at": "2019-03-20T06:48:38.634068Z"
  }
}

Error response:

{
  "status": "error",
  "message": "All dedicated IP addressess are currently taken",
  "code": 1000
}

Request an additional dedicated IP for your account.

HTTP Request

POST https://api.coresender.com/v1/ips/

Request data

field type required
pool string true

Response data

field type
data.address string
data.pool string
data.created_at string

Possible error codes

Code Description
1000 All our IPs are currently in use. You can try again later.

Delete IP

Request:

DELETE https://api.coresender.com/v1/ips/:ip/
curl --request DELETE "https://api.coresender.com/v1/ips/220.246.81.214/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": null
}

Removes a dedicated IP from your pool.

HTTP Request

DELETE https://api.coresender.com/v1/ips/:ip/

Fetch IPs

Request:

GET https://api.coresender.com/v1/ips/
curl --request GET "https://api.coresender.com/v1/ips/" \
  --header "Authorization: Bearer {{api_key}}" \
  --header "Content-Type: application/json"

Response:

{
    "status": "success",
    "data": [
        {
            "address": "172.21.0.1",
            "pool": "pool1",
            "created_at": "2019-03-20T06:48:38.634068Z"
        }
    ]
}

Fetch all IPs assigned to your account.

HTTP Request

GET https://api.coresender.com/v1/ips/

Response data

field type
data[].address string
data[].pool string
data[].created_at string

Messages

Send message

Request:

POST https://api.coresender.com/v1/messages
curl --request POST "https://api.coresender.com/v1/messages/" \
  --header "Authorization: Bearer {{api_key}}" \
  --header "Content-Type: application/json" \
  --data "{
    \"from\":{
      \"email\": \"message.from_email@example.com\",
      \"name\": \"Example name\"
    },
    \"to\": [
      {
        \"email\": \"root@simple.lan\",
        \"name\": \"Recipient name\"
      },
      {
        \"email\": \"blacklisted@example.com\"
      }
    ],
    \"subject\": \"example subject\",
    \"body\": {
      \"html\": \"<p>Example HTML content</p>\",
      \"text\": \"Example text content\"
    },
    \"images\": [
      {
        \"type\": \"image/png\",
        \"content\": \"ZXhhbXBsZSBmaWxl\",
        \"name\": \"IMAGECID\"
      }
    ],
    \"subaccount\": \"id\",
    \"ip_pool\": \"pool1\",
    \"send_at\": \"2019-02-27T23:59:59Z\",
    \"custom_id\": \"some-id\",
    \"webhook_url\": \"https://example.com/webhook\",
    \"webhook_types\": [
      \"message.delivery.error\",
      \"message.delivery.success\"
    ]
  }"
{
  "from": {                                 // Sender data (required).
    "email": "message.from_email@example.com",  // The sender email address (required).
    "name": "Example Name"                      // Optional from name.
  },
  "to": [
    {                                       // Recipient data (required).
      "email": "recipient.email@example.com",     // The email address of the recipient (required).
      "name": "Recipient Name",                   // Optional display name to use for the recipient.
    },
    {
      "email": "blacklisted@example.com"
    }
  ],
  "subject": "example subject",             // Message subject (required).
  "body": {                                 // Message body (required).
    "html": "<p>Example HTML content</p>",      // The full HTML content to be sent (required).
    "text": "Example text content"              // Optional full text content to be sent.
  },
  "images": [                               // A list of images to embed.
    {                                           // A single image data.
      "type": "image/png",                          // MIME type of the image. Must start with "image/".
      "content": "ZXhhbXBsZSBmaWxl"                 // The content of the image as a base64-encoded string.
      "name": "IMAGECID",                           // The content ID of the image - use
                                                    // <img src="cid:THIS_VALUE"> to reference the image
                                                    // in your HTML content.
    },
    ...
  ],
  "subaccount": "customer-123",                   // A id of a subaccount for this message.
  "ip_pool": "Main Pool",                         // The name of the dedicated ip pool that should be used
                                                  // to send the message. If no pool is set the message will be
                                                  // sent using shared IP's.
  "send_at": "2019-02-27T09:47:45Z",              // A time (UTC) in RFC3339 format.
  "custom_id": "some-id",                         // Custom message ID. Although is optional, we strongly recommend
                                                  // to always fill this field with unique value.
  "webhook_url": "https://example.com/webhook/",  // Webhook address where all message related webhooks will be sent.
                                                  // If empty, no webhooks will be sent
  "webhhok_types": [                              // List of webhooks types user wants to get
    "message.delivery.error",
    "message.delivery.success"
  ]
}

Response:

{
  "status": "success",
  "data": {
    "unsent": [
      {
        "recipient": "blacklisted@example.com",
        "reason": "blacklisted"
      },
      {
        "recipient": "invalid.com",
        "reason": "invalid syntax"
      }
    ]
  }
}

Send a new message.

HTTP Request

POST https://api.coresender.com/v1/messages

field type mandatory description
from.email string true Sender's email address
from.name string false Sender's name
to[].email string true Recipient's email address
to[].name string false Recipient's name
subject string true Message's subject
body.html string true Message's content in HTML format
body.text string false Message's content in text format
images[].type string true Image's MIME type. Acceptable types are: image/jpeg, image/png and image/gif
images[].content string true Image's base64 encoded content
images[].name string true Image's Content-ID
subaccount string true What subaccount message is going to be assigned to
ip_pool string false Which IP pool should be used for delivery
send_at string false Date at which message will be sent
custom_id string false Custom message ID. Although this field is optional, we strongly recommend using unique ID for every message
webhook_url string false URL where message's webhook responses will be sent
webhook_types []string false List of wanted webhook types.

Response data

field type description
unsent[].recipient string Recipient email address
unsent[].reason string Reason why email couldn't been delivered.

List of possible unsent reasons

reason description
blacklisted This recipient is blacklisted
invalid syntax The recipient's email has invalid syntax

Subaccounts

List subaccounts

Request:

GET https://api.coresender.com/v1/subaccounts/
curl --request GET "https://api.coresender.com/v1/subaccounts/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": [
    {
      "id": "123",
      "name": "ABC Widgets, Inc.",
      "description": "Free plan user, ...",
      "created_at": "2019-03-25T08:08:08.549676Z",
      "updated_at": "2019-03-25T08:08:08.549676Z",
      "sent": {
        "weekly": 42,
        "monthly": 42,
        "total": 42
      }
    }
  ]
}

Get the list of subaccounts defined for the account.

HTTP Request

GET https://api.coresender.com/v1/subaccounts/

Response data

field type description
data[].id string A unique identifier of the subaccount
data[].name string Name of subaccount
data[].description string Subaccount description
data[].created_at string Creation date
data[].updated_at string Last time when subaccount was updated
data[].sent.weekly integer Number of emails sent so far this week
data[].sent.monthly integer Number of emails sent so far this month
data[].sent.total integer Number of emails sent so far

Subaccount info

Request:

GET https://api.coresender.com/v1/subaccounts/:id/
curl --request GET "https://api.coresender.com/v1/subaccounts/id/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": {
    "id": "123",
    "name": "ABC Widgets, Inc.",
    "description": "Free plan user, ...",
    "created_at": "2019-03-25T08:08:08.549676Z",
    "updated_at": "2019-03-25T08:08:08.549676Z",
    "sent": {
      "weekly": 42,
      "monthly": 42,
      "total": 42
    }
  }
}

Return information about a single subaccount.

HTTP Request

GET https://api.coresender.com/v1/subaccounts/:id/

Response data

field type description
data.id string A unique identifier of the subaccount
data.name string Name of subaccount
data.description string Subaccount description
data.created_at string Creation date
data.updated_at string Last time when subaccount was updated
data.sent.weekly integer Number of emails sent so far this week
data.sent.monthly integer Number of emails sent so far this month
data.sent.total integer Number of emails sent so far

Create/Update subaccount

Request:

PUT https://api.coresender.com/v1/subaccounts/:id/
curl --request PUT "https://api.coresender.com/v1/subaccounts/id/" \
  --header "Authorization: Bearer {{api_key}}" \
  --header "Content-Type: application/json" \
  --data "{
    \"name\": \"ABC Widgets, Inc.\",
    \"description\": \"Free plan user, ...\"
  }"
{
  "name": "ABC Widgets, Inc.",          // Subaccount name (required).
  "description": "Free plan user, ..."  // A comment about the subaccount.
}

Response:

{
  "status": "success",
  "data": {
    "id": "id",
    "name": "ABC Widgets, Inc.",
    "description": "Free plan user, ...",
    "created_at": "2019-03-21T07:02:38.298321Z",
    "updated_at": "2019-03-21T07:02:38.298321Z",
    "sent": {
      "weekly": 6,
      "monthly": 6,
      "total": 7
    }
  }
}

Create a new subaccount. If a subaccount with the specified ID already exists, this call updates its data instead.

HTTP Request

PUT https://api.coresender.com/v1/subaccounts/:id/

Request data

field type required
name string true
description string true

Response data

field type description
data.id string A unique identifier of the subaccount
data.name string Name of subaccount
data.description string Subaccount description
data.created_at string Creation date
data.updated_at string Last time when subaccount was updated

Delete subaccount

Request:

DELETE https://api.coresender.com/v1/subaccounts/:id/
curl --request DELETE "https://api.coresender.com/v1/subaccounts/id/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": null
}

Delete an existing subaccount.

HTTP Request

DELETE https://api.coresender.com/v1/subaccounts/:id/

Blacklist

List blacklisted emails

Request:

GET https://api.coresender.com/v1/subaccounts/:id/blacklist/
curl --request GET "https://api.coresender.com/v1/subaccounts/id/blacklist/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": [
    {
      "email": "test@test.com",
      "created_at": "2019-03-21T10:16:36.389399Z"
    },
    {
      "email": "test3@test.com",
      "created_at": "2019-03-21T10:16:36.389399Z"
    }
  ]
}

Returns emails that are blacklisted for the given subaccount.

HTTP Request

GET https://api.coresender.com/v1/subaccounts/:id/blacklist/

Response data

field type description
data[].email string Blacklisted email
data[].created_at string Creation date

Delete a blacklist entry

Request:

DELETE https://api.coresender.com/v1/subaccounts/:id/blacklist/:email/
curl --request DELETE "https://api.coresender.com/v1/subaccounts/id/blacklist/test2@test.com/" \
  --header "Authorization: Bearer {{api_key}}"

Response:

{
  "status": "success",
  "data": null
}

Delete an email from the blacklist.

HTTP Request

DELETE https://api.coresender.com/v1/subaccounts/:id/blacklist/:email/

Add blacklist entries

Request:

PATCH https://api.coresender.com/v1/subaccounts/:id/blacklist/
{
  "emails": [
    "email1@example.com",
    "email2@example.com",
    ...
  ]
}
curl --request PATCH "https://api.coresender.com/v1/subaccounts/id/blacklist/" \
  --header "Authorization: Bearer {{api_key}}" \
  --header "Content-Type: application/json" \
  --data "{
    \"emails\": [
      \"test@test.com\",
      \"test2@test.com\",
      \"test3@test.com\"
    ]
  }"

Response:

{
  "status": "success",
  "data": [
    {
      "email": "email1@example.com",
      "created_at": "2019-03-21T10:16:36.389399Z"
    },
    {
      "email": "email2@example.com",
      "created_at": "2019-03-21T10:16:36.389399Z"
    }
  ]
}

Add blacklisted emails to the subaccount.

HTTP Request

PATCH https://api.coresender.com/v1/subaccounts/:id/blacklist/

Request data

field type required
emails []string true

Response data

field type description
data[].email string blacklisted email
data[].created_at string creation date

Webhooks

Core Sender is using webhooks to notify verious messages events. Every webhook is sent using HTTPS POST method.

Webhook object

All webhooks have similar body construction, where only data object varies.

Webhooks types are recognized using type field.

Types are defined there.

Example webhook body:

{
  "type": "some.webhook.type",
  "created_at": "2019-03-21T10:16:36.389399Z",
  "data": {}
}

Webhook data

field type description
type string Webhook's type
created_at string Webhook's creation date
data object Webhook's body, varies according to webhook's type

Webhook types

All webhooks have one of types mentioned below:

Message delivery success

This webhook notifies about successful message delivery.

Example webhook body:

{
  "type": "message.delivery.success",
  "created_at": "2019-03-21T10:16:36.389399Z",
  "data": {
    "recipient_email": "recipient.email@example.com",
    "custom_id": "some-id",
    "token": "token"
  }
}

Webhook data

field type description
type string Webhook's type
created_at string Webhook's creation date
data.recipient_email string Recipient's email address
data.custom_id string Custom ID set in the send message request
data.token string Message's token

Message delivery error

This webhook notifies about not successful message delivery.

Example webhook body:

{
  "type": "message.delivery.error",
  "created_at": "2019-03-21T10:16:36.389399Z",
  "data": {
    "recipient_email": "bounced@example.com",
    "custom_id": "some-id",
    "token": "token",
    "error": {
      "code": 2001,
      "message": "Message couldn't been delivered, because recipient's email address is invalid"
    }
  }
}

Webhook data

field type description
type string Webhook's type
created_at string Webhook's creation date
data.recipient_email string Recipient's email address
data.custom_id string Custom ID set in the send message request
data.token string Message's token
data.error error Additional error information, present only with error status. Described there

Message delivery errors

Table below contains all possible errors in message delivery webhook.

error code description
soft bounced 2000 For some reason message couldn't be delivered.
hard bounced 2001 Recipient's email address is invalid.

Error object

Example error body:

{
  "code": 2001,
  "message": "Message couldn't been delivered, because recipient's email address is invalid"
}

Error object represents error, present in webhooks to provide more information about problems.

field type description
code float64 Error's numeric code
message string Message describing what caused the error

API Errors

Example error body:

{
  "status": "error",
  "message": "All dedicated IP addresses are currently taken.",
  "code": 1000
}

Core Sender API may return various types of errors. All of them are contained in the table below:

Error Code Description
1000 This error may happen when provisioning new IP address. It means that all our IPs are currently assigned.
1001 This error may happen when sending message. It means that one of attached images is invalid.
1002 This error may happen when requesting resource. It means that resource wasn't found.
1003 This error may happen when sending message. It means that IP pool wasn't found.
1004 This error may happen when sending message. It means that subaccount wasn't found.