Coresender API documentation

/v1/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_email

curl -X POST https://api.coresender.com/v1/send_email \
  -u 'account_id:api_key' \
  -d $'[
    {
      "from": {
        "email": "jean.luc@example.com",
        "name": "Jean-Luc Picard"
      },
      "to": [
        { 
          "email": "geordi@example.com",
          "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": "captain@example.com",
          "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_email

curl -X POST https://api.coresender.com/v1/send_email \
  -u 'account_id:api_key' \
  -d $'[
    {
      "from": {
        "email": "jean.luc@example.com",
        "name": "Jean-Luc Picard"
      },
      "to": [
        { 
          "email": "geordi@example.com",
          "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": "captain@example.com",
          "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_uniqueboolean

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

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

Log in

This is a standard OAuth login method. Will work out of the box with your favorite OAuth library or API tools like Postman or Paw.

Arguments

emailREQUIRED string

Email address of the user logging in.

passwordREQUIRED string

Password of the user logging in.

grant_typeREQUIRED string

Always set to "password".

Returns

Returns an access_token that can be used to authenticate API calls.

POST/v1/login

curl -X POST https://api.coresender.com/v1/login \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "email": "tasha@example.com",
    "password": ".2H[xr{kd'-}pYw+.9gPG72ej%;u>Zn",
    "grant_type": "password"
  }'

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ1eXBiOiJK…",
  "refresh_token": "cef502114b84…"
}

Log in

This is a standard OAuth login method. Will work out of the box with your favorite OAuth library or API tools like Postman or Paw.

POST/v1/login

curl -X POST https://api.coresender.com/v1/login \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "email": "tasha@example.com",
    "password": ".2H[xr{kd'-}pYw+.9gPG72ej%;u>Zn",
    "grant_type": "password"
  }'

Arguments

emailREQUIRED string

Email address of the user logging in.

passwordREQUIRED string

Password of the user logging in.

grant_typeREQUIRED string

Always set to "password".

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ1eXBiOiJK…",
  "refresh_token": "cef502114b84…"
}

Returns

Returns an access_token that can be used to authenticate API calls.

Log out

Log out a user session.

Returns

200 OK

POST/v1/logout

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

Log out

Log out a user session.

POST/v1/logout

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

Returns

200 OK

Messages

With the messages API you can retrieve the status of each and every email you send. For each message, the related events can be retrieved. The message and events data are available for the duration of the log retention period.

Endpoints

/v1/messages/{message_id}

/v1/messages/{message_id}/events

The message object

Attributes

message_iduuid

Unique identifier for the email message.

custom_idstring

Custom ID for the message. This ID was added to send email when the email was sent.

recipient_emailstring

Recipient's email address.

from_emailstring

Sender's email address.

subjectstring

Email subject.

domain_iduuid

ID of the domain that the email was sent from.

account_iduuid

ID of the sending account that the email was sent from.

domain_namestring

Name of the sending domain.

account_namestring

Name of the sending account.

created_attimestamp

Time at which the email was accepted for delivery.

updated_attimestamp

Time at which the object was last updated.

delivery_statusstring

Delivery status of the email. One of: new (accepted for delivery), delivery, soft_bounce, hard_bounce.

opened_attimestamp

Time at which the email was first opened.

clicked_attimestamp

Time at which the email was first clicked.

unsubscribed_attimestamp

Time at which the recipient unsubscribed.

spam_complaint_attimestamp

Time at which the recipient filed a spam complaint.

The message object

{
  "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
  "custom_id": "abcd-1234",
  "recipient_email": "geordi@example.com",
  "from_email": "jean.luc@example.com",
  "subject": "I need engines",
  "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
  "account_id": "647d8122-e240-4993-995d-a629713678ce",
  "domain_name": "example.com",
  "account_name": "Starfleet Notifications",
  "created_at": "2022-03-14T17:00:04.397857+00:00",
  "updated_at": "2022-03-14T17:00:04.399655+00:00",
  "delivery_status": "delivery",
  "opened_at": null,
  "clicked_at": null,
  "unsubscribed_at": null,
  "spam_complaint_at": null
}

The message object

{
  "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
  "custom_id": "abcd-1234",
  "recipient_email": "geordi@example.com",
  "from_email": "jean.luc@example.com",
  "subject": "I need engines",
  "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
  "account_id": "647d8122-e240-4993-995d-a629713678ce",
  "domain_name": "example.com",
  "account_name": "Starfleet Notifications",
  "created_at": "2022-03-14T17:00:04.397857+00:00",
  "updated_at": "2022-03-14T17:00:04.399655+00:00",
  "delivery_status": "delivery",
  "opened_at": null,
  "clicked_at": null,
  "unsubscribed_at": null,
  "spam_complaint_at": null
}

Attributes

message_iduuid

Unique identifier for the email message.

custom_idstring

Custom ID for the message. This ID was added to send email when the email was sent.

recipient_emailstring

Recipient's email address.

from_emailstring

Sender's email address.

subjectstring

Email subject.

domain_iduuid

ID of the domain that the email was sent from.

account_iduuid

ID of the sending account that the email was sent from.

domain_namestring

Name of the sending domain.

account_namestring

Name of the sending account.

created_attimestamp

Time at which the email was accepted for delivery.

updated_attimestamp

Time at which the object was last updated.

delivery_statusstring

Delivery status of the email. One of: new (accepted for delivery), delivery, soft_bounce, hard_bounce.

opened_attimestamp

Time at which the email was first opened.

clicked_attimestamp

Time at which the email was first clicked.

unsubscribed_attimestamp

Time at which the recipient unsubscribed.

spam_complaint_attimestamp

Time at which the recipient filed a spam complaint.

Retrieve a message

Retrieves the details of an email message. You only need to supply a unique identifier.

Returns

Returns a message object if a valid identifier was provided.

GET/v1/messages/{message_id}

curl https://api.coresender.com/v1/messages/5e3a03a0-befc-4924-9c38-673020c9d687 \
  -H 'Authorization: Bearer oauth_access_token' \

Response

{
  "data": {
    "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
    "custom_id": "abcd-1234",
    "recipient_email": "geordi@example.com",
    "from_email": "jean.luc@example.com",
    "subject": "I need engines",
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "domain_name": "example.com",
    "account_name": "Starfleet Notifications",
    "created_at": "2022-03-14T17:00:04.397857+00:00",
    "updated_at": "2022-03-14T17:00:04.399655+00:00",
    "delivery_status": "delivery",
    "opened_at": null,
    "clicked_at": null,
    "unsubscribed_at": null,
    "spam_complaint_at": null
  },
  "meta": {
    "rq_time": "0.0016s"
  }
}

Retrieve a message

Retrieves the details of an email message. You only need to supply a unique identifier.

GET/v1/messages/{message_id}

curl https://api.coresender.com/v1/messages/5e3a03a0-befc-4924-9c38-673020c9d687 \
  -H 'Authorization: Bearer oauth_access_token' \

Response

{
  "data": {
    "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
    "custom_id": "abcd-1234",
    "recipient_email": "geordi@example.com",
    "from_email": "jean.luc@example.com",
    "subject": "I need engines",
    "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
    "account_id": "647d8122-e240-4993-995d-a629713678ce",
    "domain_name": "example.com",
    "account_name": "Starfleet Notifications",
    "created_at": "2022-03-14T17:00:04.397857+00:00",
    "updated_at": "2022-03-14T17:00:04.399655+00:00",
    "delivery_status": "delivery",
    "opened_at": null,
    "clicked_at": null,
    "unsubscribed_at": null,
    "spam_complaint_at": null
  },
  "meta": {
    "rq_time": "0.0016s"
  }
}

Returns

Returns a message object if a valid identifier was provided.

List messages

List email messages with optional filter applied.

Arguments

period_fromoptional timestamp URL query parameter

The starting date of the period for which you want to retrieve messages. The default value is today's date.

period_tooptional timestamp URL query parameter

The ending date of the period for which you want to retrieve messages. The default value is today minus 60 days.

account_ids[]optional uuid URL query parameter

Filter by the sending account that the email was sent from. If you'd like to filter by more than one sending account, you can use this parameter multiple times.

domain_ids[]optional uuid URL query parameter

Filter by the domain that the email was sent from. If you'd like to filter by more than one domain, you can use this parameter multiple times.

events[]optional string URL query parameter

Filter by the event type. Only email messages that have events of this type will be returned. Allowed values: new, delivery, hard_bounce, soft_bounce, unsibscribe, spam_complaint, open, click. If you'd like to filter by more than one event type, you can use this parameter multiple times.

recipient_emailoptional string URL query parameter

Filter by recipient email address.

from_emailoptional string URL query parameter

Filter by the From email address.

subjectoptional string URL query parameter

Filter by email subject.

message_idoptional uuid URL query parameter

Filter by the email message ID.

message_custom_idoptional string URL query parameter

Filter by your Custom ID of the email message.

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 message objects if the request succeeds. Returns an error if anything goes wrong.

GET/v1/messages

curl https://api.coresender.com/v1/messages \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2022-03-01' \
  -d 'period_to=2022-03-14' \
  -d 'events[]=hard_bounce' \
  -d 'events[]=soft_bounce' \
  -d 'account_ids[]=a3c69540-3324-49a7-b595-5c310d9ca867' \
  -d 'account_ids[]=c6d49a5a-3513-4d20-8eac-d67396dbb2e9' \
  -d 'domain_ids[]=a90409c1-3e2e-4ea5-c885-ba9554629e50' \
  -d 'subject=engines' \
  -d 'recipient_email=gmail.com' \
  -d 'from_email=hello' \
  -d 'offset=0' \
  -d 'limit=30' \

Response

{
  "data": [
    {
      "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
      …
    },
    {
      "message_id": "06691710-63be-4253-a58f-aa0f58bbdbc2",
      …
    }
  ],
  "meta": {
    "limit": 30,
    "offset": "0",
    "total": 2,
    "rq_time": "0.0016s"
  }
}

List messages

List email messages with optional filter applied.

GET/v1/messages

curl https://api.coresender.com/v1/messages \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2022-03-01' \
  -d 'period_to=2022-03-14' \
  -d 'events[]=hard_bounce' \
  -d 'events[]=soft_bounce' \
  -d 'account_ids[]=a3c69540-3324-49a7-b595-5c310d9ca867' \
  -d 'account_ids[]=c6d49a5a-3513-4d20-8eac-d67396dbb2e9' \
  -d 'domain_ids[]=a90409c1-3e2e-4ea5-c885-ba9554629e50' \
  -d 'subject=engines' \
  -d 'recipient_email=gmail.com' \
  -d 'from_email=hello' \
  -d 'offset=0' \
  -d 'limit=30' \

Arguments

period_fromoptional timestamp URL query parameter

The starting date of the period for which you want to retrieve messages. The default value is today's date.

period_tooptional timestamp URL query parameter

The ending date of the period for which you want to retrieve messages. The default value is today minus 60 days.

account_ids[]optional uuid URL query parameter

Filter by the sending account that the email was sent from. If you'd like to filter by more than one sending account, you can use this parameter multiple times.

domain_ids[]optional uuid URL query parameter

Filter by the domain that the email was sent from. If you'd like to filter by more than one domain, you can use this parameter multiple times.

events[]optional string URL query parameter

recipient_emailoptional string URL query parameter

Filter by recipient email address.

from_emailoptional string URL query parameter

Filter by the From email address.

subjectoptional string URL query parameter

Filter by email subject.

message_idoptional uuid URL query parameter

Filter by the email message ID.

message_custom_idoptional string URL query parameter

Filter by your Custom ID of the email message.

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": [
    {
      "message_id": "5e3a03a0-befc-4924-9c38-673020c9d687",
      …
    },
    {
      "message_id": "06691710-63be-4253-a58f-aa0f58bbdbc2",
      …
    }
  ],
  "meta": {
    "limit": 30,
    "offset": "0",
    "total": 2,
    "rq_time": "0.0016s"
  }
}

Returns

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

Export messages to CSV

Retrieves a list of email messages as a CSV file.

Arguments

period_fromoptional timestamp URL query parameter

The starting date of the period for which you want to retrieve messages. The default value is today's date.

period_tooptional timestamp URL query parameter

The ending date of the period for which you want to retrieve messages. The default value is today minus 60 days.

account_ids[]optional uuid URL query parameter

Filter by the sending account that the email was sent from. If you'd like to filter by more than one sending account, you can use this parameter multiple times.

domain_ids[]optional uuid URL query parameter

Filter by the domain that the email was sent from. If you'd like to filter by more than one domain, you can use this parameter multiple times.

events[]optional string URL query parameter

recipient_emailoptional string URL query parameter

Filter by recipient email address.

from_emailoptional string URL query parameter

Filter by the From email address.

subjectoptional string URL query parameter

Filter by email subject.

message_idoptional uuid URL query parameter

Filter by the email message ID.

message_custom_idoptional string URL query parameter

Filter by your Custom ID of the email message.

Returns

A CSV file (text/csv).

GET/v1/messages/export

curl https://api.coresender.com/v1/messages/export \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2022-03-01' \
  -d 'period_to=2022-03-14' \
  -d 'events[]=hard_bounce' \
  -d 'events[]=soft_bounce' \
  -d 'account_ids[]=a3c69540-3324-49a7-b595-5c310d9ca867' \
  -d 'account_ids[]=c6d49a5a-3513-4d20-8eac-d67396dbb2e9' \
  -d 'domain_ids[]=a90409c1-3e2e-4ea5-c885-ba9554629e50' \
  -d 'subject=engines' \
  -d 'recipient_email=example.com' \
  -d 'from_email=jean' \

Response

message_id,custom_id,recipient_email,from_email,subject,domain_id,account_id,domain_name,account_name,created_at,updated_at,opened_at,clicked_at,unsubscribed_at,delivery_status,spam_complaint_at,smtp_response
5e3a03a0-befc-4924-9c38-673020c9d687,,geordi@example.com,jean.luc@example.com,"I need engines",a90409c1-3e2e-4ea5-c885-ba9554629e50,647d8122-e240-4993-995d-a629713678ce,example.com,"Starfleet Notifications","2022-03-16 07:37:35","2022-03-16 07:37:37","2022-03-16 07:37:37",,,delivery,,"250 2.0.0 OK  1643416256 q5-20020a05651c034500b002491edf6829si1192676ljp.338 - examplecom"

Export messages to CSV

Retrieves a list of email messages as a CSV file.

GET/v1/messages/export

curl https://api.coresender.com/v1/messages/export \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2022-03-01' \
  -d 'period_to=2022-03-14' \
  -d 'events[]=hard_bounce' \
  -d 'events[]=soft_bounce' \
  -d 'account_ids[]=a3c69540-3324-49a7-b595-5c310d9ca867' \
  -d 'account_ids[]=c6d49a5a-3513-4d20-8eac-d67396dbb2e9' \
  -d 'domain_ids[]=a90409c1-3e2e-4ea5-c885-ba9554629e50' \
  -d 'subject=engines' \
  -d 'recipient_email=example.com' \
  -d 'from_email=jean' \

Arguments

period_fromoptional timestamp URL query parameter

The starting date of the period for which you want to retrieve messages. The default value is today's date.

period_tooptional timestamp URL query parameter

The ending date of the period for which you want to retrieve messages. The default value is today minus 60 days.

account_ids[]optional uuid URL query parameter

Filter by the sending account that the email was sent from. If you'd like to filter by more than one sending account, you can use this parameter multiple times.

domain_ids[]optional uuid URL query parameter

Filter by the domain that the email was sent from. If you'd like to filter by more than one domain, you can use this parameter multiple times.

events[]optional string URL query parameter

recipient_emailoptional string URL query parameter

Filter by recipient email address.

from_emailoptional string URL query parameter

Filter by the From email address.

subjectoptional string URL query parameter

Filter by email subject.

message_idoptional uuid URL query parameter

Filter by the email message ID.

message_custom_idoptional string URL query parameter

Filter by your Custom ID of the email message.

Response

message_id,custom_id,recipient_email,from_email,subject,domain_id,account_id,domain_name,account_name,created_at,updated_at,opened_at,clicked_at,unsubscribed_at,delivery_status,spam_complaint_at,smtp_response
5e3a03a0-befc-4924-9c38-673020c9d687,,geordi@example.com,jean.luc@example.com,"I need engines",a90409c1-3e2e-4ea5-c885-ba9554629e50,647d8122-e240-4993-995d-a629713678ce,example.com,"Starfleet Notifications","2022-03-16 07:37:35","2022-03-16 07:37:37","2022-03-16 07:37:37",,,delivery,,"250 2.0.0 OK  1643416256 q5-20020a05651c034500b002491edf6829si1192676ljp.338 - examplecom"

Returns

A CSV file (text/csv).

The event object

Attributes

received_attimestamp

Time at which the event happened.

typestring

One of: new, delivery, hard_bounce, soft_bounce, spam_complaint, unsubscribe, open, click.

details{}object

Contains additional data, depending on the event type.

details.user_agentstring

Available for open and click events. Contains the User-Agent of the browser that was used to open or click the message.

details.user_ipstring

Available for open and click events. Contains the IP address of the device that was used to open or click the message.

details.smtp_responsestring

Available for delivery and hard_bounce and soft_bounce events. Contains the response line of a remote SMTP server.

details.smtp_log_iduuid

Available for delivery and hard_bounce and soft_bounce events. Contains the identifier of the SMTP delivery log.

details.list_idstring

Available for unsubscribe. Contains the list_id of the message.

The event object

{
  "received_at": "2022-03-16T07:37:37.963662+00:00",
  "type": "open",
  "details": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0",
    "user_ip": "10.10.10.10"
  }
}

The event object

{
  "received_at": "2022-03-16T07:37:37.963662+00:00",
  "type": "open",
  "details": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0",
    "user_ip": "10.10.10.10"
  }
}

Attributes

received_attimestamp

Time at which the event happened.

typestring

One of: new, delivery, hard_bounce, soft_bounce, spam_complaint, unsubscribe, open, click.

details{}object

Contains additional data, depending on the event type.

details.user_agentstring

Available for open and click events. Contains the User-Agent of the browser that was used to open or click the message.

details.user_ipstring

Available for open and click events. Contains the IP address of the device that was used to open or click the message.

details.smtp_responsestring

Available for delivery and hard_bounce and soft_bounce events. Contains the response line of a remote SMTP server.

details.smtp_log_iduuid

Available for delivery and hard_bounce and soft_bounce events. Contains the identifier of the SMTP delivery log.

details.list_idstring

Available for unsubscribe. Contains the list_id of the message.

List events for a message

List events related to a message with a given identifier.

Returns

Returns a list of event objects if a valid identifier was provided.

GET/v1/messages/{message_id}/events

curl https://api.coresender.com/v1/messages/5e3a03a0-befc-4924-9c38-673020c9d687/events \
  -H 'Authorization: Bearer oauth_access_token' \

Response

{
  "data": [
    {
      "received_at": "2022-03-16T07:37:36.187956+00:00",
      "type": "delivery",
      …
    },
    {
      "received_at": "2022-03-16T07:37:35.483000+00:00",
      "type": "new",
      …
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 3,
    "rq_time": "0.0010s"
  }
}

List events for a message

List events related to a message with a given identifier.

GET/v1/messages/{message_id}/events

curl https://api.coresender.com/v1/messages/5e3a03a0-befc-4924-9c38-673020c9d687/events \
  -H 'Authorization: Bearer oauth_access_token' \

Response

{
  "data": [
    {
      "received_at": "2022-03-16T07:37:36.187956+00:00",
      "type": "delivery",
      …
    },
    {
      "received_at": "2022-03-16T07:37:35.483000+00:00",
      "type": "new",
      …
    }
  ],
  "meta": {
    "limit": 30,
    "offset": 0,
    "total": 3,
    "rq_time": "0.0010s"
  }
}

Returns

Returns a list of event objects if a valid identifier was provided.

Statistics

Coresender provides aggregated statistics for all emailing activity. Use this API if you need to learn how is your emailing performing in terms of delivery and engagement.

Endpoints

/v1/stats

The statistics object

Attributes

period_fromtimestamp

The start of the date range for which the statistics are returned.

period_totimestamp

The end of the date range for which the statistics are returned.

stats_summaryobject

Aggregated metrics for the selected date range.

stats_summary.messagesinteger

The number of emails accepted for delivery.

stats_summary.deliveryinteger

The number of delivered emails.

stats_summary.hard_bounceinteger

The number of hard bounce events.

stats_summary.soft_bounceinteger

The number of soft bounce events.

stats_summary.spam_complaintinteger

The number of spam complaints.

stats_summary.unsubscribeinteger

The number of unsubscribes.

stats_summary.openinteger

The number of email opens

stats_summary.track_opensinteger

The number of emails for which opens have been tracked.

stats_summary.clickinteger

The number of link clicks in emails.

stats_summary.track_clicksinteger

The number of emails for which clicks have been tracked.

stats_summary.unique_opensinteger

The number of unique emails that have been opened.

stats_summary.unique_clicksinteger

The number of unique emails that have been clicked.

breakdownarray

Each item of this array contains statistic for a particular sending account or sending domain.

breakdown[].account_iduuid

ID of the sending account that the breakdown covers.

breakdown[].account_nameuuid

Name of the sending account that the breakdown covers.

breakdown[].domain_iduuid

ID of the domain that the breakdown covers.

breakdown[].domain_nameuuid

Name of the domain that the breakdown covers.

The statistics object

{
  "period_from": "2022-03-07",
  "period_to": "2022-03-14",
  "stats_summary": {
    "messages": "7415",
    "delivery": "7385",
    "hard_bounce": "0",
    "soft_bounce": "29",
    "spam_complaint": "0",
    "unsubscribe": "0",
    "open": "5681",
    "track_opens": "7378",
    "click": "5681",
    "track_clicks": "7378",
    "unique_opens": "5681",
    "unique_clicks": "5681"
  },
  "breakdown": [
    {
      "messages": "21",
      "delivery": "21",
      "hard_bounce": "0",
      "soft_bounce": "0",
      "spam_complaint": "0",
      "unsubscribe": "0",
      "open": "0",
      "track_opens": "0",
      "click": "0",
      "track_clicks": "0",
      "unique_opens": "0",
      "unique_clicks": "0",
      "account_id": "647d8122-e240-4993-995d-a629713678ce",
      "account_name": "Starfleet Notifications"
    },
    {
      "messages": "7415",
      "delivery": "7385",
      "hard_bounce": "0",
      "soft_bounce": "29",
      "spam_complaint": "0",
      "unsubscribe": "0",
      "open": "5681",
      "track_opens": "7378",
      "click": "5681",
      "track_clicks": "7378",
      "unique_opens": "5681",
      "unique_clicks": "5681",
      "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
      "domain_name": "example.com"
    }
  ]
}

The statistics object

{
  "period_from": "2022-03-07",
  "period_to": "2022-03-14",
  "stats_summary": {
    "messages": "7415",
    "delivery": "7385",
    "hard_bounce": "0",
    "soft_bounce": "29",
    "spam_complaint": "0",
    "unsubscribe": "0",
    "open": "5681",
    "track_opens": "7378",
    "click": "5681",
    "track_clicks": "7378",
    "unique_opens": "5681",
    "unique_clicks": "5681"
  },
  "breakdown": [
    {
      "messages": "21",
      "delivery": "21",
      "hard_bounce": "0",
      "soft_bounce": "0",
      "spam_complaint": "0",
      "unsubscribe": "0",
      "open": "0",
      "track_opens": "0",
      "click": "0",
      "track_clicks": "0",
      "unique_opens": "0",
      "unique_clicks": "0",
      "account_id": "647d8122-e240-4993-995d-a629713678ce",
      "account_name": "Starfleet Notifications"
    },
    {
      "messages": "7415",
      "delivery": "7385",
      "hard_bounce": "0",
      "soft_bounce": "29",
      "spam_complaint": "0",
      "unsubscribe": "0",
      "open": "5681",
      "track_opens": "7378",
      "click": "5681",
      "track_clicks": "7378",
      "unique_opens": "5681",
      "unique_clicks": "5681",
      "domain_id": "a90409c1-3e2e-4ea5-c885-ba9554629e50",
      "domain_name": "example.com"
    }
  ]
}

Attributes

period_fromtimestamp

The start of the date range for which the statistics are returned.

period_totimestamp

The end of the date range for which the statistics are returned.

stats_summaryobject

Aggregated metrics for the selected date range.

stats_summary.messagesinteger

The number of emails accepted for delivery.

stats_summary.deliveryinteger

The number of delivered emails.

stats_summary.hard_bounceinteger

The number of hard bounce events.

stats_summary.soft_bounceinteger

The number of soft bounce events.

stats_summary.spam_complaintinteger

The number of spam complaints.

stats_summary.unsubscribeinteger

The number of unsubscribes.

stats_summary.openinteger

The number of email opens

stats_summary.track_opensinteger

The number of emails for which opens have been tracked.

stats_summary.clickinteger

The number of link clicks in emails.

stats_summary.track_clicksinteger

The number of emails for which clicks have been tracked.

stats_summary.unique_opensinteger

The number of unique emails that have been opened.

stats_summary.unique_clicksinteger

The number of unique emails that have been clicked.

breakdownarray

Each item of this array contains statistic for a particular sending account or sending domain.

breakdown[].account_iduuid

ID of the sending account that the breakdown covers.

breakdown[].account_nameuuid

Name of the sending account that the breakdown covers.

breakdown[].domain_iduuid

ID of the domain that the breakdown covers.

breakdown[].domain_nameuuid

Name of the domain that the breakdown covers.

Retrieve statistics

Returns aggregated statistics for the requested time period.

Arguments

period_fromrequired timestamp URL query parameter

The starting date of the period for which you want to retrieve the statistics.

period_torequired timestamp URL query parameter

The ending date of the period for which you want to retrieve the statistics.

Returns

Returns the statistics object if the request succeeds. stats_summary is always returned. The breakdown section is returned when breaking down by sending accounts or domains is requested. Returns an error if anything goes wrong.

GET/v1/stats

curl https://api.coresender.com/v1/stats \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2022-03-07' \
  -d 'period_to=2022-03-14' \
  -d 'all_accounts=0' \
  -d 'all_domains=0' \

Response

{
  "data": {
    "period_from": "2022-03-07",
    "period_to": "2022-03-14",
    "stats_summary": {
      "messages": "7415",
      "delivery": "7385",
      "hard_bounce": "0",
      "soft_bounce": "29",
      "spam_complaint": "0",
      "unsubscribe": "0",
      "open": "5681",
      "track_opens": "7378",
      "click": "5681",
      "track_clicks": "7378",
      "unique_opens": "5681",
      "unique_clicks": "5681"
    }
  },
  "meta": {
    "rq_time": "0.0005s"
  }
}

Retrieve statistics

Returns aggregated statistics for the requested time period.

GET/v1/stats

curl https://api.coresender.com/v1/stats \
  -H 'Authorization: Bearer oauth_access_token' \
  -G \
  -d 'period_from=2022-03-07' \
  -d 'period_to=2022-03-14' \
  -d 'all_accounts=0' \
  -d 'all_domains=0' \

Arguments

period_fromrequired timestamp URL query parameter

The starting date of the period for which you want to retrieve the statistics.

period_torequired timestamp URL query parameter

The ending date of the period for which you want to retrieve the statistics.

Response

{
  "data": {
    "period_from": "2022-03-07",
    "period_to": "2022-03-14",
    "stats_summary": {
      "messages": "7415",
      "delivery": "7385",
      "hard_bounce": "0",
      "soft_bounce": "29",
      "spam_complaint": "0",
      "unsubscribe": "0",
      "open": "5681",
      "track_opens": "7378",
      "click": "5681",
      "track_clicks": "7378",
      "unique_opens": "5681",
      "unique_clicks": "5681"
    }
  },
  "meta": {
    "rq_time": "0.0005s"
  }
}

Returns

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

/v1/accounts

/v1/accounts/{account_id}

PATCH

/v1/accounts/{account_id}

DELETE

/v1/accounts/{account_id}

/v1/accounts

The sending account object

Attributes

account_iduuid

Unique identifier for the sending account.

namestring

Name of the sending account.

typestring

Type of the sending account. Can be either transactional or marketing. The type can not be changed.

statusstring

The status of the sending account. Can be either active or disabled.

The sending account object

{
  "account_id": "647d8122-e240-4993-995d-a629713678ce",
  "name": "Starfleet Notifications",
  "status": "active",
  "type": "transactional"
}

The sending account object

{
  "account_id": "647d8122-e240-4993-995d-a629713678ce",
  "name": "Starfleet Notifications",
  "status": "active",
  "type": "transactional"
}

Attributes

account_iduuid

Unique identifier for the sending account.

namestring

Name of the sending account.

typestring

Type of the sending account. Can be either transactional or marketing. The type can not be changed.

statusstring

The status of the sending account. Can be either active or disabled.

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/accounts

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/accounts

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}

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}

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}

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}

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}

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}

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 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/accounts

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 sending accounts

List all sending accounts with optional filters applied.

GET/v1/accounts

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

/v1/domains

/v1/domains/{domain_id}

PATCH

/v1/domains/{domain_id}

DELETE

/v1/domains/{domain_id}

/v1/domains

/v1/domains/{domain_id}/verify_dkim

/v1/domains/{domain_id}/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

{
  "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/domains

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/domains

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}

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}

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}

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}

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}

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}

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 sending domains

List all domains 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/domains

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 sending domains

List all domains with optional filters applied.

GET/v1/domains

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_dkim

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_dkim

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_path

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_path

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

/v1/suppressions

/v1/suppressions/{suppression_id}

DELETE

/v1/suppressions/{suppression_id}

/v1/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": "redshirt@example.com",
  "type": "hard_bounce"
}

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": "redshirt@example.com",
  "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

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/suppressions

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": "tasha@example.com"
  }'

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": "tasha@example.com",
    "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/suppressions

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": "tasha@example.com"
  }'

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": "tasha@example.com",
    "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}

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": "tasha@example.com",
    "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}

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": "tasha@example.com",
    "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}

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": "tasha@example.com",
    "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}

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": "tasha@example.com",
    "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 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/suppressions

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": "tasha@example.com",
      "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 suppressions

Lists all suppressions with optional filters applied.

GET/v1/suppressions