SonarSend API Sending Sending Setup

Sending Setup

Before an integration can create or schedule a usable broadcast, it usually needs to understand three SonarSend concepts:

  • email types
  • sending identities
  • MTA configs

These work together to determine how a broadcast is classified, which senders are eligible, and which delivery path is used.

Email types#

An email type describes what kind of email is being sent.

Examples:

  • prospect_newsletter
  • customer_updates
  • product_announcements

In the external API, email types are referenced by:

  • email_type_key

Read them with:

GET /api/email-types

Required scope:

  • sending-identities:read

Use an email type when:

  • creating a broadcast draft
  • choosing eligible sending identities
  • keeping analytics and classification consistent

Sending identities#

A sending identity is the actual sender mailbox and related display configuration.

Examples:

  • ops@example.com
  • newsletter@example.com

In the external API, sending identities are referenced by:

  • sending_identity_emails

Read them with:

GET /api/sending-identities

Required scope:

  • sending-identities:read

Use sender email addresses in broadcast payloads when:

  • you want to restrict sending to a specific identity
  • you want the draft to open in SonarSend with the sender already chosen

If you omit sending_identity_emails, SonarSend may still be able to resolve an eligible delivery pool from the email type and MTA config.

MTA configs#

An MTA config describes the delivery path SonarSend should use for the broadcast.

Examples:

  • primary-mail
  • backup-transactional

In the external API, MTA configs are referenced by:

  • mta_config_key

The configurations themselves are not readable over the API — they describe the sending supply chain rather than anything an integration decides. mta_config_key is optional on a broadcast: omit it and SonarSend resolves an eligible delivery path from the email type and sending identity. If you do want to pin one, copy the key from the app where sending providers are configured.

How they fit together#

For most broadcast integrations, the relationship is:

  1. choose an email_type_key
  2. optionally restrict the broadcast to one or more sending_identity_emails
  3. optionally pin the delivery path with an mta_config_key

Example:

{
  "email_type_key": "prospect_newsletter",
  "mta_config_key": "primary-mail",
  "sending_identity_emails": ["ops@example.com"]
}

Before creating a draft, have your integration read:

  • /api/email-types
  • /api/sending-identities

Then store the friendly identifiers in your own system:

  • type_key
  • sender email address
  • mta_config_key, if you pin a delivery path

This avoids hard-coding internal UUIDs and makes payloads easier to understand when debugging.

Common pitfalls#

  • Do not pass an internal email type UUID in place of email_type_key.
  • Do not pass an internal MTA UUID in place of mta_config_key.
  • Do not assume every sender email is valid for every email type or MTA.
  • Do not give an integration broadcasts:schedule unless it should truly be allowed to send.