Mobile menu icon
Coresender
Mobile menu close icon
Coresender

Overview

Endpoint URL

The Coresender API follows the basic REST style. All methods provided by the API are accessible from the same base endpoint. We require SSL encryption when using our API so no unencrypted endpoint is available.

Endpoint URL

https://api.coresender.com

Endpoint URL

The Coresender API follows the basic REST style. All methods provided by the API are accessible from the same base endpoint. We require SSL encryption when using our API so no unencrypted endpoint is available.

Endpoint URL

https://api.coresender.com

Authentication

Coresender's public API provides methods with three different authentication levels:

  • No authentication – Used for publicly open methods, such as registering, logging in, requesting a password reset.
  • OAuth – Used for most API methods to manage your sending accounts, domains, users but also to access your statistics or activity logs. The login procedure should be performed with the Log in method.
  • Basic Auth – Used for sending out emails from your sending accounts. This is a standard HTTP Basic authentication. The username is your sending account ID and the password is one of the API keys added for a particular sending account.

The authentication method is always shown in the request example.

Authentication

Coresender's public API provides methods with three different authentication levels:

  • No authentication – Used for publicly open methods, such as registering, logging in, requesting a password reset.
  • OAuth – Used for most API methods to manage your sending accounts, domains, users but also to access your statistics or activity logs. The login procedure should be performed with the Log in method.
  • Basic Auth – Used for sending out emails from your sending accounts. This is a standard HTTP Basic authentication. The username is your sending account ID and the password is one of the API keys added for a particular sending account.

The authentication method is always shown in the request example.

HTTP response codes

We use a set of HTTP response codes to let you know about the status of your API requests or the nature of an error. Below you'll find the list of codes as well as their general usage.

  • 200 OK – Used for letting you know that your request succeeded. For GET requests it means that the response contains no errors and the data is being delivered. For PUT and DELETE requests it means that the operation succeeded.
  • 201 Created – Used by POST requests to let you know that the object was successfully created.
  • 207 Multi-Status – Used by Send email to indicate that at least one of your emails was rejected.
  • 400 Bad Request – Used when the JSON body of your request is invalid. See INVALID_JSON error code.
  • 401 Unauthorized – Used when API is called with proper authorization, eg. invalid login and password, invalid access token, invalid API key.
  • 403 Forbidden – Used when the requested resource is not available because of permissions.
  • 404 Not Found – We have reserved this code for one purpose only: letting you know that the API endpoint that you send a request to does not exist. If you see 404, look for a typo. When an unexistent resource (eg. User, Domain) is requested, 409 will be returned.
  • 409 Conflict – Used when a request fails because of business logic, including when some resources involved are not found.
  • 422 Unprocessable Entity – Used for validation errors.
  • 429 Too Many Requests – Used when the API requests-per-minute limit is reached. It's our way of telling you to slow down.
  • 500 – There is an internal issue with processing your request. If you sent an email, assume that it's lost and retry.

HTTP response codes

We use a set of HTTP response codes to let you know about the status of your API requests or the nature of an error. Below you'll find the list of codes as well as their general usage.

  • 200 OK – Used for letting you know that your request succeeded. For GET requests it means that the response contains no errors and the data is being delivered. For PUT and DELETE requests it means that the operation succeeded.
  • 201 Created – Used by POST requests to let you know that the object was successfully created.
  • 207 Multi-Status – Used by Send email to indicate that at least one of your emails was rejected.
  • 400 Bad Request – Used when the JSON body of your request is invalid. See INVALID_JSON error code.
  • 401 Unauthorized – Used when API is called with proper authorization, eg. invalid login and password, invalid access token, invalid API key.
  • 403 Forbidden – Used when the requested resource is not available because of permissions.
  • 404 Not Found – We have reserved this code for one purpose only: letting you know that the API endpoint that you send a request to does not exist. If you see 404, look for a typo. When an unexistent resource (eg. User, Domain) is requested, 409 will be returned.
  • 409 Conflict – Used when a request fails because of business logic, including when some resources involved are not found.
  • 422 Unprocessable Entity – Used for validation errors.
  • 429 Too Many Requests – Used when the API requests-per-minute limit is reached. It's our way of telling you to slow down.
  • 500 – There is an internal issue with processing your request. If you sent an email, assume that it's lost and retry.

Send email

Email sending API uses an HTTP basic authentication, with account_id as username and api_key as password. You can add multiple API keys to your sending accounts.

Endpoints
POST
/v1/send_email
Send email

Send email

Your sending account's account_id and api_key are required to authenticate. You will find them in your control panel.

Arguments

from.emailREQUIRED string

Sender's email address.

from.namestring

Sender's name.

to[].emailREQUIRED string

Recipient's email address. Only one recipient is supported. Array is here for future expansion.

to[].namestring

Recipient's name.

subjectREQUIRED string

Email subject

body.htmlstring

HTML email body. Required if body.text not present.

body.textstring

Text email body. Required if body.html not present.

custom_idstring

Custom ID for the message. This ID will be returned in API response, will be included in webhooks and you will be able to search by it with the Messages API. Additionally it will be added to your email as X-Message-Custom-Id header.

custom_id_uniqueboolean

When enabled, custom_id will be required be unique within a period of the last 72 hours. This is handy for senders who want to repeat a certain batch of emails with a guarantee that no email will be sent more than once.

track_opensboolean

Enables tracking email opens whenever possible. Tracking pixel will be added to the HTML part of the message.

track_clicksboolean

Enables tracking links clicks. URLs within the email will be replaced with tracking URLs and the recipient will be redirected to the original URL on every click.

list_idstring

An email distribution list identifier used by the email client built-in unsubscribe feature.

list_unsubscribestring

Either an email or URL which will receive an unsubscription request if the recipient decides to use email client's built-in unsubscribe feature. If email address is provided, then we will forward an original unsubscription message sent by the inbox provider. If URL is provided, we will redirect a recipient to this URL so they can continue the unsubscription procedure on your end.

reply_to[].emailstring

An email address of an entry that will be added to email's Reply-To header.

reply_to[].namestring

A visible name of an entry that will be added to email's Reply-To header.

POST/v1/send_emailClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/send_email \
  -u 'account_id:api_key' \
  -d $'[
    {
      "from": {
        "email": "[email protected]",
        "name": "Jean-Luc Picard"
      },
      "to": [
        { 
          "email": "[email protected]",
          "name": "Geordi La Forge"
        }
      ],
      "subject": "I need engines",
      "body": {
        "html": "<p>Geordi, I need engines, <strong>now!</strong></p>",
        "text": "Geordi, I need engines, now!"
      },
      "custom_id": "abcd-1234",
      "custom_id_unique": false,
      "track_opens": true,
      "track_clicks": true,
      "list_id": "crew-orders",
      "list_unsubscribe": "https://example.com/unsubscribe/abcd-1234",
      "reply_to": [
        {
          "email": "[email protected]",
          "name": "Captain"
        }
      ]
    }
  ]'
Response 
{
  "data": [
    {
      "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
      "custom_id": "abcd-1234",
      "status": "accepted",
      "errors": []
    },
  ],
  "meta": {
  }
}

Send email

Your sending account's account_id and api_key are required to authenticate. You will find them in your control panel.

POST/v1/send_emailClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/send_email \
  -u 'account_id:api_key' \
  -d $'[
    {
      "from": {
        "email": "[email protected]",
        "name": "Jean-Luc Picard"
      },
      "to": [
        { 
          "email": "[email protected]",
          "name": "Geordi La Forge"
        }
      ],
      "subject": "I need engines",
      "body": {
        "html": "<p>Geordi, I need engines, <strong>now!</strong></p>",
        "text": "Geordi, I need engines, now!"
      },
      "custom_id": "abcd-1234",
      "custom_id_unique": false,
      "track_opens": true,
      "track_clicks": true,
      "list_id": "crew-orders",
      "list_unsubscribe": "https://example.com/unsubscribe/abcd-1234",
      "reply_to": [
        {
          "email": "[email protected]",
          "name": "Captain"
        }
      ]
    }
  ]'

Arguments

from.emailREQUIRED string

Sender's email address.

from.namestring

Sender's name.

to[].emailREQUIRED string

Recipient's email address. Only one recipient is supported. Array is here for future expansion.

to[].namestring

Recipient's name.

subjectREQUIRED string

Email subject

body.htmlstring

HTML email body. Required if body.text not present.

body.textstring

Text email body. Required if body.html not present.

custom_idstring

Custom ID for the message. This ID will be returned in API response, will be included in webhooks and you will be able to search by it with the Messages API. Additionally it will be added to your email as X-Message-Custom-Id header.

custom_id_uniqueboolean

When enabled, custom_id will be required be unique within a period of the last 72 hours. This is handy for senders who want to repeat a certain batch of emails with a guarantee that no email will be sent more than once.

track_opensboolean

Enables tracking email opens whenever possible. Tracking pixel will be added to the HTML part of the message.

track_clicksboolean

Enables tracking links clicks. URLs within the email will be replaced with tracking URLs and the recipient will be redirected to the original URL on every click.

list_idstring

An email distribution list identifier used by the email client built-in unsubscribe feature.

list_unsubscribestring

Either an email or URL which will receive an unsubscription request if the recipient decides to use email client's built-in unsubscribe feature. If email address is provided, then we will forward an original unsubscription message sent by the inbox provider. If URL is provided, we will redirect a recipient to this URL so they can continue the unsubscription procedure on your end.

reply_to[].emailstring

An email address of an entry that will be added to email's Reply-To header.

reply_to[].namestring

A visible name of an entry that will be added to email's Reply-To header.

Response 
{
  "data": [
    {
      "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
      "custom_id": "abcd-1234",
      "status": "accepted",
      "errors": []
    },
  ],
  "meta": {
  }
}

OAuth

As most of the API uses OAuth access token as an authentication method (the only exception being Send email), relevant endpoints are provided.

Endpoints
POST
/v1/login
Log in
POST
/v1/logout
Log out

Log out

Log out a user session.

Returns

200 OK

POST/v1/logoutClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/logout \
  -H 'Authorization: Bearer oauth_access_token'

Log out

Log out a user session.

POST/v1/logoutClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/logout \
  -H 'Authorization: Bearer oauth_access_token'

Returns

200 OK

Sending accounts

In Coresender, you can organize your sending activity by using sending accounts. They have separate API keys, webhooks, and each sending account is gathering its activity logs and suppressions separately.

Sending accounts can either be transactional or marketing, depending on the emails you will send through them. Please note that Coresender requires that you always choose a proper sending account type.

You can create many sending accounts, depending on your needs. You can use them to separate your integrated applications, environments (like production or test), or your clients.

Endpoints
POST
/v1/accounts
Create a sending account
GET
/v1/accounts/{account_id}
Retrieve a sending account
PATCH
/v1/accounts/{account_id}
Update a sending account
DELETE
/v1/accounts/{account_id}
Delete a sending account
GET
/v1/accounts
List all sending accounts

Create a sending account

Creates a sending account that you will use to send your email.

Arguments

nameREQUIRED string

Name of the sending account.

typeREQUIRED string

Type of the account. Can either be transactional or marketing.

Returns

Returns the sending account object if the request succeeds. Returns an error if anything goes wrong.

POST/v1/accountsClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/accounts \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "name": "Starfleet Notifications",
    "type": "transactional"
  }'
Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Notifications",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0008s"
  }
}

Create a sending account

Creates a sending account that you will use to send your email.

POST/v1/accountsClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/accounts \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "name": "Starfleet Notifications",
    "type": "transactional"
  }'

Arguments

nameREQUIRED string

Name of the sending account.

typeREQUIRED string

Type of the account. Can either be transactional or marketing.

Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Notifications",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0008s"
  }
}

Returns

Returns the sending account object if the request succeeds. Returns an error if anything goes wrong.

Retrieve a sending account

Retrieves the details of an existing sending account. You only need to supply a unique identifier.

Returns

Returns a sending account object if a valid identifier was provided.

GET/v1/accounts/{account_id}Click to copyClick to copy 
curl https://api.coresender.com/v1/accounts/647d8122-e240-4993-995d-a629713678ce \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Notifications",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Retrieve a sending account

Retrieves the details of an existing sending account. You only need to supply a unique identifier.

GET/v1/accounts/{account_id}Click to copyClick to copy 
curl https://api.coresender.com/v1/accounts/647d8122-e240-4993-995d-a629713678ce \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Notifications",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Returns

Returns a sending account object if a valid identifier was provided.

Update a sending account

Updates the specified sending account. Note that the type of the sending account can not be updated.

Arguments

nameREQUIRED string

Name of the sending account.

Returns

Returns the sending account object if the request succeeds. Returns an error if anything goes wrong.

PATCH/v1/accounts/{account_id}Click to copyClick to copy 
curl -X PATCH https://api.coresender.com/v1/accounts/647d8122-e240-4993-995d-a629713678ce \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "name": "Starfleet Alerts",
  }'
Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Alerts",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0008s"
  }
}

Update a sending account

Updates the specified sending account. Note that the type of the sending account can not be updated.

PATCH/v1/accounts/{account_id}Click to copyClick to copy 
curl -X PATCH https://api.coresender.com/v1/accounts/647d8122-e240-4993-995d-a629713678ce \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "name": "Starfleet Alerts",
  }'

Arguments

nameREQUIRED string

Name of the sending account.

Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Alerts",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0008s"
  }
}

Returns

Returns the sending account object if the request succeeds. Returns an error if anything goes wrong.

Delete a sending account

Permanently deletes a sending account. It cannot be undone.

Returns

Returns a deleted sending account object if the request succeeds. Returns an error if anything goes wrong.

DELETE/v1/accounts/{account_id}Click to copyClick to copy 
curl -X DELETE https://api.coresender.com/v1/accounts/647d8122-e240-4993-995d-a629713678ce \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Alerts",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Delete a sending account

Permanently deletes a sending account. It cannot be undone.

DELETE/v1/accounts/{account_id}Click to copyClick to copy 
curl -X DELETE https://api.coresender.com/v1/accounts/647d8122-e240-4993-995d-a629713678ce \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "name": "Starfleet Alerts",
    "status": "active",
    "type": "transactional"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Returns

Returns a deleted sending account object if the request succeeds. Returns an error if anything goes wrong.

List all sending accounts

List all sending accounts with optional filters applied.

Arguments

nameoptional string URL query parameter

Filter by account name.

typeoptional string URL query parameter

Filter by account type. It can be either transactional or marketing.

limitoptional integer URL query parameter

Limit the response to a specified number of objects.

offsetoptional integer URL query parameter

Return objects starting from a specified offset. Counted from 0.

Returns

Returns the list of sending account objects if the request succeeds. Returns an error if anything goes wrong.

GET/v1/accountsClick to copyClick to copy 
curl https://api.coresender.com/v1/accounts \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'name=Starfleet'
Response 
{
  "data": [
    {
      "account_id": "647d8122-e240-4993-995d-a629713678ce",
      "name": "Starfleet Notifications",
      "status": "active",
      "type": "transactional"
    },
    {
      "account_id": "04a96a81-41a9-4f6d-9dfc-ffe433a7fba0",
      "name": "Starfleet Newsletters",
      "status": "active",
      "type": "marketing"
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 2,
    "rq_time": "0.0043s"
  }
}

List all sending accounts

List all sending accounts with optional filters applied.

GET/v1/accountsClick to copyClick to copy 
curl https://api.coresender.com/v1/accounts \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'name=Starfleet'

Arguments

nameoptional string URL query parameter

Filter by account name.

typeoptional string URL query parameter

Filter by account type. It can be either transactional or marketing.

limitoptional integer URL query parameter

Limit the response to a specified number of objects.

offsetoptional integer URL query parameter

Return objects starting from a specified offset. Counted from 0.

Response 
{
  "data": [
    {
      "account_id": "647d8122-e240-4993-995d-a629713678ce",
      "name": "Starfleet Notifications",
      "status": "active",
      "type": "transactional"
    },
    {
      "account_id": "04a96a81-41a9-4f6d-9dfc-ffe433a7fba0",
      "name": "Starfleet Newsletters",
      "status": "active",
      "type": "marketing"
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 2,
    "rq_time": "0.0043s"
  }
}

Returns

Returns the list of sending account objects if the request succeeds. Returns an error if anything goes wrong.

Sending domains

You will need to properly configure the first domain before you can send your first email. It includes adding DKIM and Return-Path DNS records and verifying them. We will only let you use a domain name in your email's From header if its DNS settings are verified.

Endpoints
POST
/v1/domains
Create a sending domain
GET
/v1/domains/{domain_id}
Retrieve a sending domain
PATCH
/v1/domains/{domain_id}
Update a sending domain
DELETE
/v1/domains/{domain_id}
Delete a sending domain
GET
/v1/domains
List all sending domains
POST
/v1/domains/{domain_id}/verify_dkim
Verify DKIM
POST
/v1/domains/{domain_id}/verify_return_path
Verify Return-Path

The sending domain object

Attributes

domain_iduuid

Unique identifier for the sending domain.

namestring

Name of the sending domain.

accounts[].account_iduuid

Unique identifier of the sending account that the domain is assigned to.

accounts[].nameuuid

Name of the sending account that the domain is assigned to.

dkim_verified_attimestamp

The date at which DKIM DNS records were successfully verified. null if the verification failed.

return_path_verified_attimestamp

The date at which Return-Path DNS record was successfully verified. null if the verification failed.

return_path_hostnamestring

The hostname for the Return-Path configuration.

return_path_cnamestring

The value of the Return-Path DNS record.

dkim_selector_1string

The hostname of the first DKIM DNS record.

dkim_cname_1string

The value of the first DKIM DNS record.

dkim_selector_2string

The hostname of the second DKIM DNS record.

dkim_cname_2string

The value of the second DKIM DNS record.

The sending domain object 
{
  "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
  "name": "example.com",
  "accounts": [
    {
      "account_id": "647d8122-e240-4993-995d-a629713678ce",
      "name": "Starfleet Notifications"
    }
  ],
  "dkim_verified_at": "2020-07-08T17:05:48.826002+00:00",
  "return_path_verified_at": "2020-07-03T11:17:04.812559+00:00",
  "return_path_hostname": "cs-bounces",
  "return_path_cname": "coresender.net",
  "dkim_selector_1": "cs1",
  "dkim_cname_1": "cs1.domainkey.coresender.net",
  "dkim_selector_2": "cs2",
  "dkim_cname_2": "cs2.domainkey.coresender.net",
}

The sending domain object

The sending domain object 
{
  "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
  "name": "example.com",
  "accounts": [
    {
      "account_id": "647d8122-e240-4993-995d-a629713678ce",
      "name": "Starfleet Notifications"
    }
  ],
  "dkim_verified_at": "2020-07-08T17:05:48.826002+00:00",
  "return_path_verified_at": "2020-07-03T11:17:04.812559+00:00",
  "return_path_hostname": "cs-bounces",
  "return_path_cname": "coresender.net",
  "dkim_selector_1": "cs1",
  "dkim_cname_1": "cs1.domainkey.coresender.net",
  "dkim_selector_2": "cs2",
  "dkim_cname_2": "cs2.domainkey.coresender.net",
}

Attributes

domain_iduuid

Unique identifier for the sending domain.

namestring

Name of the sending domain.

accounts[].account_iduuid

Unique identifier of the sending account that the domain is assigned to.

accounts[].nameuuid

Name of the sending account that the domain is assigned to.

dkim_verified_attimestamp

The date at which DKIM DNS records were successfully verified. null if the verification failed.

return_path_verified_attimestamp

The date at which Return-Path DNS record was successfully verified. null if the verification failed.

return_path_hostnamestring

The hostname for the Return-Path configuration.

return_path_cnamestring

The value of the Return-Path DNS record.

dkim_selector_1string

The hostname of the first DKIM DNS record.

dkim_cname_1string

The value of the first DKIM DNS record.

dkim_selector_2string

The hostname of the second DKIM DNS record.

dkim_cname_2string

The value of the second DKIM DNS record.

Create a sending domain

Creates a sending domain that you will use to send your email.

Arguments

nameREQUIRED string

Name of the sending domain.

return_path_hostnameoptional string

The hostname for the Return-Path configuration. You may want to change it if the default cs-bounces hostname is already used in your domain.

accountsREQUIRED array of uuids

A list of sending accounts IDs. The domain will get assigned to those accounts.

Returns

Returns the sending domain object if the request succeeds. Returns an error if anything goes wrong.

POST/v1/domainsClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/domains \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "name": "example.com",
    "accounts": [
      "647d8122-e240-4993-995d-a629713678ce"
    ]
  }'
Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    "accounts": [
      {
        "account_id": "647d8122-e240-4993-995d-a629713678ce",
        "name": "Starfleet Notifications"
      }
    ],
    "dkim_verified_at": null,
    "return_path_verified_at": null,
    "return_path_hostname": "cs-bounces",
    "return_path_cname": "coresender.net",
    "dkim_selector_1": "cs1",
    "dkim_cname_1": "cs1.domainkey.coresender.net",
    "dkim_selector_2": "cs2",
    "dkim_cname_2": "cs2.domainkey.coresender.net",
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Create a sending domain

Creates a sending domain that you will use to send your email.

POST/v1/domainsClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/domains \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "name": "example.com",
    "accounts": [
      "647d8122-e240-4993-995d-a629713678ce"
    ]
  }'

Arguments

nameREQUIRED string

Name of the sending domain.

return_path_hostnameoptional string

The hostname for the Return-Path configuration. You may want to change it if the default cs-bounces hostname is already used in your domain.

accountsREQUIRED array of uuids

A list of sending accounts IDs. The domain will get assigned to those accounts.

Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    "accounts": [
      {
        "account_id": "647d8122-e240-4993-995d-a629713678ce",
        "name": "Starfleet Notifications"
      }
    ],
    "dkim_verified_at": null,
    "return_path_verified_at": null,
    "return_path_hostname": "cs-bounces",
    "return_path_cname": "coresender.net",
    "dkim_selector_1": "cs1",
    "dkim_cname_1": "cs1.domainkey.coresender.net",
    "dkim_selector_2": "cs2",
    "dkim_cname_2": "cs2.domainkey.coresender.net",
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Returns

Returns the sending domain object if the request succeeds. Returns an error if anything goes wrong.

Retrieve a sending domain

Retrieves the details of an existing sending domain. You only need to supply a unique identifier.

Returns

Returns a sending domain object if a valid identifier was provided.

GET/v1/domains/{domain_id}Click to copyClick to copy 
curl https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50 \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    "accounts": [
      {
        "account_id": "647d8122-e240-4993-995d-a629713678ce",
        "name": "Starfleet Notifications"
      }
    ],
    "dkim_verified_at": null,
    "return_path_verified_at": null,
    "return_path_hostname": "cs-bounces",
    "return_path_cname": "coresender.net",
    "dkim_selector_1": "cs1",
    "dkim_cname_1": "cs1.domainkey.coresender.net",
    "dkim_selector_2": "cs2",
    "dkim_cname_2": "cs2.domainkey.coresender.net",
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Retrieve a sending domain

Retrieves the details of an existing sending domain. You only need to supply a unique identifier.

GET/v1/domains/{domain_id}Click to copyClick to copy 
curl https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50 \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    "accounts": [
      {
        "account_id": "647d8122-e240-4993-995d-a629713678ce",
        "name": "Starfleet Notifications"
      }
    ],
    "dkim_verified_at": null,
    "return_path_verified_at": null,
    "return_path_hostname": "cs-bounces",
    "return_path_cname": "coresender.net",
    "dkim_selector_1": "cs1",
    "dkim_cname_1": "cs1.domainkey.coresender.net",
    "dkim_selector_2": "cs2",
    "dkim_cname_2": "cs2.domainkey.coresender.net",
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Returns

Returns a sending domain object if a valid identifier was provided.

Update a sending domain

Updates the specified sending domain.

Arguments

return_path_hostnameoptional string

The hostname for the Return-Path configuration. You may want to change it if the default cs-bounces hostname is already used in your domain.

accountsREQUIRED array of uuids

A list of sending accounts IDs. The domain will get assigned to those accounts. All previously assigned sending accounts will be replaced.

Returns

Returns the sending domain object if the request succeeds. Returns an error if anything goes wrong.

PATCH/v1/domains/{domain_id}Click to copyClick to copy 
curl -X PATCH https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50 \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "return_path_hostname": "mail",
    "accounts": [
      "647d8122-e240-4993-995d-a629713678ce",
      "04a96a81-41a9-4f6d-9dfc-ffe433a7fba0"
    ]
  }'
Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    "accounts": [
      {
        "account_id": "647d8122-e240-4993-995d-a629713678ce",
        "name": "Starfleet Notifications"
      },
      {
        "account_id": "04a96a81-41a9-4f6d-9dfc-ffe433a7fba0",
        "name": "Starfleet Newsletters",
      }
    ],
    "dkim_verified_at": null,
    "return_path_verified_at": null,
    "return_path_hostname": "mail",
    "return_path_cname": "coresender.net",
    "dkim_selector_1": "cs1",
    "dkim_cname_1": "cs1.domainkey.coresender.net",
    "dkim_selector_2": "cs2",
    "dkim_cname_2": "cs2.domainkey.coresender.net",
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Update a sending domain

Updates the specified sending domain.

PATCH/v1/domains/{domain_id}Click to copyClick to copy 
curl -X PATCH https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50 \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "return_path_hostname": "mail",
    "accounts": [
      "647d8122-e240-4993-995d-a629713678ce",
      "04a96a81-41a9-4f6d-9dfc-ffe433a7fba0"
    ]
  }'

Arguments

return_path_hostnameoptional string

The hostname for the Return-Path configuration. You may want to change it if the default cs-bounces hostname is already used in your domain.

accountsREQUIRED array of uuids

A list of sending accounts IDs. The domain will get assigned to those accounts. All previously assigned sending accounts will be replaced.

Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    "accounts": [
      {
        "account_id": "647d8122-e240-4993-995d-a629713678ce",
        "name": "Starfleet Notifications"
      },
      {
        "account_id": "04a96a81-41a9-4f6d-9dfc-ffe433a7fba0",
        "name": "Starfleet Newsletters",
      }
    ],
    "dkim_verified_at": null,
    "return_path_verified_at": null,
    "return_path_hostname": "mail",
    "return_path_cname": "coresender.net",
    "dkim_selector_1": "cs1",
    "dkim_cname_1": "cs1.domainkey.coresender.net",
    "dkim_selector_2": "cs2",
    "dkim_cname_2": "cs2.domainkey.coresender.net",
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Returns

Returns the sending domain object if the request succeeds. Returns an error if anything goes wrong.

Delete a sending domain

Permanently deletes a sending domain. It cannot be undone.

Returns

Returns a deleted sending domain object if the request succeeds. Returns an error if anything goes wrong.

DELETE/v1/domains/{domain_id}Click to copyClick to copy 
curl -X DELETE https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50 \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    …
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Delete a sending domain

Permanently deletes a sending domain. It cannot be undone.

DELETE/v1/domains/{domain_id}Click to copyClick to copy 
curl -X DELETE https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50 \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "name": "example.com",
    …
  },
  "meta": {
    "rq_time": "0.0071s"
  }
}

Returns

Returns a deleted sending domain object if the request succeeds. Returns an error if anything goes wrong.

List all sending domains

List all sending accounts with optional filters applied.

Arguments

nameoptional string URL query parameter

Filter by the domain name.

limitoptional integer URL query parameter

Limit the response to a specified number of objects.

offsetoptional integer URL query parameter

Return objects starting from a specified offset. Counted from 0.

Returns

Returns the list of sending account objects if the request succeeds. Returns an error if anything goes wrong.

GET/v1/domainsClick to copyClick to copy 
curl https://api.coresender.com/v1/domains \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'name=example'
Response 
{
  "data": [
    {
      "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
      "name": "example.com",
      …
    },
    {
      "domain_id": "fa8c1873-7e66-4712-9dd2-f7844d90448c",
      "name": "example.net",
      …
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 2,
    "rq_time": "0.0043s"
  }
}

List all sending domains

List all sending accounts with optional filters applied.

GET/v1/domainsClick to copyClick to copy 
curl https://api.coresender.com/v1/domains \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'name=example'

Arguments

nameoptional string URL query parameter

Filter by the domain name.

limitoptional integer URL query parameter

Limit the response to a specified number of objects.

offsetoptional integer URL query parameter

Return objects starting from a specified offset. Counted from 0.

Response 
{
  "data": [
    {
      "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
      "name": "example.com",
      …
    },
    {
      "domain_id": "fa8c1873-7e66-4712-9dd2-f7844d90448c",
      "name": "example.net",
      …
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 2,
    "rq_time": "0.0043s"
  }
}

Returns

Returns the list of sending account objects if the request succeeds. Returns an error if anything goes wrong.

Verify DKIM

Checks your domain's DNS and verifies if DKIM-related hosts are properly configured.

Returns

Returns 200 OK if the verification succeeds. Returns an error if anything goes wrong.

POST/v1/domains/{domain_id}/verify_dkimClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50/verify_dkim \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": "OK",
  "meta": {
    "rq_time":"0.0003s"
  }
}

Verify DKIM

Checks your domain's DNS and verifies if DKIM-related hosts are properly configured.

POST/v1/domains/{domain_id}/verify_dkimClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50/verify_dkim \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": "OK",
  "meta": {
    "rq_time":"0.0003s"
  }
}

Returns

Returns 200 OK if the verification succeeds. Returns an error if anything goes wrong.

Verify Return-Path

Checks your domain's DNS and verifies if Return-Path host is properly configured.

Returns

Returns 200 OK if the verification succeeds. Returns an error if anything goes wrong.

POST/v1/domains/{domain_id}/verify_return_pathClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50/verify_return_path \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": "OK",
  "meta": {
    "rq_time":"0.0003s"
  }
}

Verify Return-Path

Checks your domain's DNS and verifies if Return-Path host is properly configured.

POST/v1/domains/{domain_id}/verify_return_pathClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/domains/a90409c1-3e2e-4ea5-c885-ba9554629e50/verify_return_path \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": "OK",
  "meta": {
    "rq_time":"0.0003s"
  }
}

Returns

Returns 200 OK if the verification succeeds. Returns an error if anything goes wrong.

Suppressions

Coresender keeps lists of recipients' email addresses it rejects to deliver to. Each sending account has its own suppression list. Email addresses are suppressed when the message hard‑bounces, when it's flagged as spam by the recipient, or when the recipient decided to use the list-unsubscribe feature. You can also manually add and delete suppressions using this Suppressions API.

Endpoints
POST
/v1/suppressions
Create a suppression
GET
/v1/suppressions/{suppression_id}
Retrieve a suppression
DELETE
/v1/suppressions/{suppression_id}
Delete a suppression
GET
/v1/suppressions
List all suppressions

The suppression object

Attributes

suppression_iduuid

Unique identifier for the suppression.

account_iduuid

ID of the sending account the suppression belongs to.

account_namestring

Name of the sending account the suppression belongs to.

created_attimestamp

Time at which suppression was created.

message_custom_idstring

Your custom ID for the Message the suppression is a result of. Will be empty if type is manual.

message_iduuid

ID for the Message the suppression is a result of. Will be empty if type is manual.

reasonstring

The reason why the suppression was added. Only if type is manual.

recipient_emailstring

The suppressed email address.

typestring

Suppression type. If the suppression was manually added (either via API or control panel) the value is manual. If added automatically by the system, the value is one of hard_bounce, spam_complaint and unsubscribe.

The suppression object 
{
  "suppression_id": "cdea3870-0d1b-4c10-983c-fb2719af9755",
  "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
  "account_name": "My transactionals",
  "created_at": "2020-03-22T17:19:03.000117+00:00",
  "message_custom_id": "abcd-1234",
  "message_id": "4808ce75-f745-4afd-ad23-200ee061215b",
  "reason": "",
  "recipient_email": "[email protected]",
  "type": "hard_bounce"
}

The suppression object

The suppression object 
{
  "suppression_id": "cdea3870-0d1b-4c10-983c-fb2719af9755",
  "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
  "account_name": "My transactionals",
  "created_at": "2020-03-22T17:19:03.000117+00:00",
  "message_custom_id": "abcd-1234",
  "message_id": "4808ce75-f745-4afd-ad23-200ee061215b",
  "reason": "",
  "recipient_email": "[email protected]",
  "type": "hard_bounce"
}

Attributes

suppression_iduuid

Unique identifier for the suppression.

account_iduuid

ID of the sending account the suppression belongs to.

account_namestring

Name of the sending account the suppression belongs to.

created_attimestamp

Time at which suppression was created.

message_custom_idstring

Your custom ID for the Message the suppression is a result of. Will be empty if type is manual.

message_iduuid

ID for the Message the suppression is a result of. Will be empty if type is manual.

reasonstring

The reason why the suppression was added. Only if type is manual.

recipient_emailstring

The suppressed email address.

typestring

Suppression type. If the suppression was manually added (either via API or control panel) the value is manual. If added automatically by the system, the value is one of hard_bounce, spam_complaint and unsubscribe.

Create a suppression

Creating suppressions with the API is an equivalent of adding them in the control panel. The type is always set to manual.

Arguments

account_idREQUIRED uuid

ID of the sending account the suppression is going to belong to.

reasonstring

The reason why you are suppressing this recipient.

recipient_emailREQUIRED string

The suppressed email address.

Returns

Returns the suppression object if the request succeeds. Returns an error if anything goes wrong.

POST/v1/suppressionsClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/suppressions \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "reason": "Imported from our internal system",
    "recipient_email": "[email protected]"
  }'
Response 
{
  "data": {
    "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "account_name": "My transactionals",
    "created_at": "2020-03-23T06:50:38.049041+00:00",
    "recipient_email": "[email protected]",
    "message_id": null,
    "message_custom_id": null,
    "type": "manual",
    "reason": "Imported from our internal system"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Create a suppression

Creating suppressions with the API is an equivalent of adding them in the control panel. The type is always set to manual.

POST/v1/suppressionsClick to copyClick to copy 
curl -X POST https://api.coresender.com/v1/suppressions \
  -H 'Authorization: Bearer oauth_access_token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "reason": "Imported from our internal system",
    "recipient_email": "[email protected]"
  }'

Arguments

account_idREQUIRED uuid

ID of the sending account the suppression is going to belong to.

reasonstring

The reason why you are suppressing this recipient.

recipient_emailREQUIRED string

The suppressed email address.

Response 
{
  "data": {
    "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "account_name": "My transactionals",
    "created_at": "2020-03-23T06:50:38.049041+00:00",
    "recipient_email": "[email protected]",
    "message_id": null,
    "message_custom_id": null,
    "type": "manual",
    "reason": "Imported from our internal system"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Returns

Returns the suppression object if the request succeeds. Returns an error if anything goes wrong.

Retrieve a suppression

Retrieves the details of an existing suppression. You only need to supply a unique suppression identifier.

Returns

Returns a suppression object if a valid identifier was provided.

GET/v1/suppressions/{suppression_id}Click to copyClick to copy 
curl https://api.coresender.com/v1/suppressions/b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "account_name": "My transactionals",
    "created_at": "2020-03-23T06:50:38.049041+00:00",
    "recipient_email": "[email protected]",
    "message_id": null,
    "message_custom_id": null,
    "type": "manual",
    "reason": "Imported from our internal system"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Retrieve a suppression

Retrieves the details of an existing suppression. You only need to supply a unique suppression identifier.

GET/v1/suppressions/{suppression_id}Click to copyClick to copy 
curl https://api.coresender.com/v1/suppressions/b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "account_name": "My transactionals",
    "created_at": "2020-03-23T06:50:38.049041+00:00",
    "recipient_email": "[email protected]",
    "message_id": null,
    "message_custom_id": null,
    "type": "manual",
    "reason": "Imported from our internal system"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Returns

Returns a suppression object if a valid identifier was provided.

Delete a suppression

Permanently deletes a suppression. It cannot be undone.

Returns

Returns a deleted suppression object on success.

DELETE/v1/suppressions/{suppression_id}Click to copyClick to copy 
curl -X DELETE https://api.coresender.com/v1/suppressions/b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "account_name": "My transactionals",
    "created_at": "2020-03-23T06:50:38.049041+00:00",
    "recipient_email": "[email protected]",
    "message_id": null,
    "message_custom_id": null,
    "type": "manual",
    "reason": "Imported from our internal system"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Delete a suppression

Permanently deletes a suppression. It cannot be undone.

DELETE/v1/suppressions/{suppression_id}Click to copyClick to copy 
curl -X DELETE https://api.coresender.com/v1/suppressions/b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f \
  -H 'Authorization: Bearer oauth_access_token'
Response 
{
  "data": {
    "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
    "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
    "account_name": "My transactionals",
    "created_at": "2020-03-23T06:50:38.049041+00:00",
    "recipient_email": "[email protected]",
    "message_id": null,
    "message_custom_id": null,
    "type": "manual",
    "reason": "Imported from our internal system"
  },
  "meta": {
    "rq_time": "0.0043s"
  }
}

Returns

Returns a deleted suppression object on success.

List all suppressions

Lists all suppressions with optional filters applied.

Arguments

account_ids[]optional uuid URL query parameter

Filter by a sending account. If you'd like to filter by multiple sending accounts, you can use this parameter multiple times.

period_fromoptional timestamp URL query parameter

The starting date of the period you want to filter by.

period_tooptional timestamp URL query parameter

The ending date of the period you want to filter by.

recipient_emailoptional string URL query parameter

Filter by recipient email address. Note: one recipient can be suppressed in multiple sending accounts.

message_idoptional uuid URL query parameter

Filter by the ID of the message the suppression is a result of.

message_custom_idoptional string URL query parameter

Filter by your custom ID of the message the suppression is a result of.

types[]optional string URL query parameter

Filter by the suppression type. If you'd like to filter by more than one type, you can use this parameter multiple times.

reasonoptional string URL query parameter

Filter by the suppression reason provided when the suppression was created.

limitoptional integer URL query parameter

Limit the response to a specified number of objects.

offsetoptional integer URL query parameter

Return objects starting from a specified offset. Counted from 0.

Returns

Returns the list of suppression objects if the request succeeds. Returns an error if filters are invalid (e.g. wong date format or nonexistent sending account).

GET/v1/suppressionsClick to copyClick to copy 
curl https://api.coresender.com/v1/suppressions \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2020-02-01' \
  -d 'period_to=2020-02-29' \
  -d 'account_ids[]=a3c69540-3324-49a7-b595-5c310d9ca867' \
  -d 'account_ids[]=c6d49a5a-3513-4d20-8eac-d67396dbb2e9' \
  -d 'types[]=manual'
Response 
{
  "data": [
    {
      "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
      "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
      "account_name": "My transactionals",
      "created_at": "2020-03-23T06:50:38.049041+00:00",
      "recipient_email": "[email protected]",
      "message_id": null,
      "message_custom_id": null,
      "type": "manual",
      "reason": "Imported from our internal system"
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 1,
    "rq_time": "0.0043s"
  }
}

List all suppressions

Lists all suppressions with optional filters applied.

GET/v1/suppressionsClick to copyClick to copy 
curl https://api.coresender.com/v1/suppressions \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2020-02-01' \
  -d 'period_to=2020-02-29' \
  -d 'account_ids[]=a3c69540-3324-49a7-b595-5c310d9ca867' \
  -d 'account_ids[]=c6d49a5a-3513-4d20-8eac-d67396dbb2e9' \
  -d 'types[]=manual'

Arguments

account_ids[]optional uuid URL query parameter

Filter by a sending account. If you'd like to filter by multiple sending accounts, you can use this parameter multiple times.

period_fromoptional timestamp URL query parameter

The starting date of the period you want to filter by.

period_tooptional timestamp URL query parameter

The ending date of the period you want to filter by.

recipient_emailoptional string URL query parameter

Filter by recipient email address. Note: one recipient can be suppressed in multiple sending accounts.

message_idoptional uuid URL query parameter

Filter by the ID of the message the suppression is a result of.

message_custom_idoptional string URL query parameter

Filter by your custom ID of the message the suppression is a result of.

types[]optional string URL query parameter

Filter by the suppression type. If you'd like to filter by more than one type, you can use this parameter multiple times.

reasonoptional string URL query parameter

Filter by the suppression reason provided when the suppression was created.

limitoptional integer URL query parameter

Limit the response to a specified number of objects.

offsetoptional integer URL query parameter

Return objects starting from a specified offset. Counted from 0.

Response 
{
  "data": [
    {
      "suppression_id": "b87aa3b3-8aa3-4fd2-8a50-0bdcb16a1e4f",
      "account_id": "a3c69540-3324-49a7-b595-5c310d9ca867",
      "account_name": "My transactionals",
      "created_at": "2020-03-23T06:50:38.049041+00:00",
      "recipient_email": "[email protected]",
      "message_id": null,
      "message_custom_id": null,
      "type": "manual",
      "reason": "Imported from our internal system"
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 1,
    "rq_time": "0.0043s"
  }
}

Returns

Returns the list of suppression objects if the request succeeds. Returns an error if filters are invalid (e.g. wong date format or nonexistent sending account).

Webhooks overview

Webhooks are requests made from Coresender back to your application whenever specific events occur.

Testing webhooks

You can use Webhooks.site for testing your webhooks.

Testing webhooks

You can use Webhooks.site for testing your webhooks.

Delivery webhook

This webhook is triggered whenever your message is successfully delivered to the receiving server.

Delivery webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.delivery"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Delivery webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.delivery"
}

Delivery webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Delivery webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.delivery"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.delivery"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Hard bounce webhook

This webhook is triggered whenever your message delivery attempt results in a hard bounce.

Hard bounce webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.hard_bounce"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Hard bounce webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.hard_bounce"
}

Hard bounce webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Hard bounce webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.hard_bounce"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.hard_bounce"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Soft bounce webhook

This webhook is triggered whenever your message delivery attempt results in a soft bounce.

Soft bounce webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.soft_bounce"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Soft bounce webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.soft_bounce"
}

Soft bounce webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Soft bounce webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.soft_bounce"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.soft_bounce"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Spam complaint webhook

This webhook is triggered whenever your message is marked as spam by the recipient.

Spam complaint webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.spam_complaint"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Spam complaint webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.spam_complaint"
}

Spam complaint webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Spam complaint webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "event": "message.spam_complaint"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.spam_complaint"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Unsubscribe webhook

This webhook is triggered whenever the recipient uses an unsubscribe feature built into the email client they are using, e.g., Gmail's "Unsubscribe" link at the top of the message.

Unsubscribe webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.unsubscribe"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

list_idstring

The list identifier, as specified in the List-Id header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Unsubscribe webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "list_id": "company_newsletters",
  "event": "message.unsubscribe"
}

Unsubscribe webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Unsubscribe webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "list_id": "company_newsletters",
  "event": "message.unsubscribe"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.unsubscribe"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

list_idstring

The list identifier, as specified in the List-Id header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

Open tracking webhook

This webhook is triggered whenever your message is opened by the recipient.

Open tracking webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.open"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

user_agentstring

The User-Agent of the browser that was used to open the message.

Open tracking webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36"
  "event": "message.open"
}

Open tracking webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Open tracking webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36"
  "event": "message.open"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.open"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

user_agentstring

The User-Agent of the browser that was used to open the message.

Click tracking webhook

This webhook is triggered whenever the recipient clicks on links in your message.

Click tracking webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.click"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

user_agentstring

The User-Agent of the browser that was used to click on the link.

Click tracking webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36"
  "event": "message.click"
}

Click tracking webhook data

To the right is the example of the JSON that would be sent to your Webhook URL. Bellow is a description of all the fields.

Click tracking webhook data 
{
  "received_at": "2020-02-24T12:15:30.617352+00:00",
  "message_id": "a3045f2b-ee5c-492e-a9b9-2017b5187b01",
  "custom_id": "abcd-1234",
  "recipient_email": "[email protected]",
  "from_email": "[email protected]",
  "account_id": "7b0ac663-d3f4-4d2d-9095-bc4cdd118287",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36"
  "event": "message.click"
}

Attributes

account_iduuid

Identifier of the sending account that was used to send the email.

custom_idstring

Custom ID that you have provided when you sent a message.

eventstring, value is "message.click"

Type of the event that triggered the webhook.

from_emailstring

Email address used in the From header.

message_iduuid

Unique identifier for the message.

received_attimestamp

Time at which the event happened.

recipient_emailstring

Email address of the recipient.

user_agentstring

The User-Agent of the browser that was used to click on the link.