Configure Sender Accounts via API

Create and update email and LinkedIn sender accounts programmatically

Note: This guide covers API-based configuration. For manual setup via the UI, see our Configure Senders UI guide.

Endpoint

POST https://api.outreachmagic.io/v1/senders

Headers:

• x-api-key: {{YOUR_API_KEY}}
• content-type: application/json

What This API Does

The senders endpoint lets you create or update sender accounts in Outreach Magic. Sender accounts represent the email addresses or LinkedIn profiles that send your outbound campaigns.

Email Senders

Provide an email address (e.g., spencer@outreachmagic.io) to create or update an email sender account.

LinkedIn Senders

Provide a LinkedIn profile URL (e.g., https://linkedin.com/in/username) to create or update a LinkedIn sender account.

Automatic Detection: If the value includes @, it's treated as an email sender. If it starts with http, it's treated as a LinkedIn sender.

Behavior:

• If sender already exists → it is updated with new metadata
• If sender doesn't exist → it is created
• You can send one sender or multiple senders in a batch

Why Sender Metadata Matters

Providing accurate sender metadata directly powers your Deliverability Reports and helps Outreach Magic analyze deliverability patterns, sending infrastructure quality, and inbox reputation signals.

Deliverability Analysis

• See which senders land in inbox vs. spam
• Identify senders with degraded reputation
• Detect domain-level issues

Infrastructure Insights

• Compare cheap vs. premium inboxes
• Detect server-level issues (Google, Outreach, etc.)
• Identify problematic inbox providers

Better Reporting

• Workspace-level deliverability tracking
• Platform-level comparison
• Domain vs. inbox health analysis

Bounce Classification

• Improved bounce categorization
• ISP-specific detection
• Infrastructure-level trend mapping

Tip: The cleaner your sender metadata, the more accurate your deliverability insights become.

Request Examples

Minimal Example

The simplest request. If workspace_id is not provided, the sender is placed into Unassigned Senders.

{
  "sender": "spencer@outreachmagic.io"
}

Recommended Example

Always include workspace_id to ensure senders are assigned to the correct workspace.

{
  "sender": "spencer@outreachmagic.io",
  "workspace_id": "68eb4080934e8e34e771819c"
}

Full Example (All Fields)

Complete example with all optional metadata fields for maximum deliverability insights.

{
  "sender": "spencer@outreachmagic.io",
  "sender_name": "Spencer McMurtry",
  "workspace_id": "68eb4080934e8e34e771819c",
  "type": "email",
  "email_server": "google",
  "email_reseller": "premium_inboxes",
  "platform": "instantly"
}

cURL Example

Complete cURL command for testing the API.

curl -X POST "https://api.outreachmagic.io/v1/senders" \
  -H "x-api-key: {{YOUR_API_KEY}}" \
  -H "content-type: application/json" \
  -d '{
    "sender": "spencer@outreachmagic.io",
    "sender_name": "Spencer McMurtry",
    "workspace_id": "68eb4080934e8e34e771819c",
    "type": "email",
    "email_server": "google",
    "email_reseller": "premium_inboxes",
    "platform": "instantly"
  }'

Field Reference

Field	Required	Description
`sender`	✔	Email address OR LinkedIn profile URL
`workspace_id`	Optional	Defaults to Unassigned Senders if not provided
`sender_name`	Optional	Human-readable name for the sender
`type`	Optional	`"email"` or `"linkedin"` (auto-detected if omitted)
`email_server`	Optional	e.g. `google`, `outreach`, `private_smtp`
`email_reseller`	Optional	e.g. `premium_inboxes`, `cheap_inboxes`, `zapmail`
`platform`	Optional	Source system: `smartlead`, `instantly`, `plusvibe`, etc.

Email Reseller Options

• cheap_inboxes
• premium_inboxes
• zapmail
• ci_aged
• Custom values supported

Email Server Options

• google
• outreach
• private_smtp
• zoho
• microsoft
• Custom values supported

Response Format

Success Response

Whether you send one sender or many, Outreach Magic returns a structured summary:

{
  "breakdown": {
    "created": 0,
    "total": 1,
    "updated": 1
  },
  "errors": {
    "count": 0,
    "details": []
  },
  "success": 1,
  "total": 1
}

Response Fields:

• breakdown.created - Number of new senders created
• breakdown.updated - Number of existing senders updated
• breakdown.total - Total senders processed
• success - Number of successful operations
• errors.count - Number of items that failed
• errors.details - Error details (indexed by item)

Error Responses

Invalid API Key:

{"error": "Invalid API key provided"}

Missing sender field:

{"error": "sender field is required"}

Common Use Cases

Syncing from Cold Email Platforms

Automatically sync senders from SmartLead, Instantly, PlusVibe, HeyReach, Apollo, and other platforms.

LinkedIn Sender Mapping

Map LinkedIn senders from HeyReach, Expandi, We-Connect, Dripify, and other LinkedIn automation tools.

Agency Workspace Assignment

Automatically assign senders to correct client workspaces for multi-client outbound management.

Automation Pipelines

Integrate with Clay, n8n, Make.com, Zapier, and custom systems for automated sender sync.

Frequently Asked Questions

Does sender metadata improve deliverability reporting?

Yes — sender metadata powers nearly all deliverability diagnostics and ISP-level insights in Outreach Magic.

Can I send LinkedIn URLs?

Yes — simply provide a LinkedIn profile URL (e.g., https://linkedin.com/in/username). Outreach Magic will automatically detect it as a LinkedIn sender.

What if workspace_id isn't provided?

The sender is automatically stored in Unassigned Senders. You can reassign it later via the UI or API.

Can I send multiple senders at once?

Yes — simply POST an array of sender objects. The API will process all senders and return a summary of created/updated items.

What happens if I send a sender twice?

The existing sender is updated with the new metadata. No duplicate is created.

Ready to Get Started?

Start managing your sender accounts programmatically and improve your deliverability reporting.

Get Your API Key View UI Guide