> For the complete documentation index, see [llms.txt](https://run.emailchaser.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://run.emailchaser.com/api-reference/sender-emails.md).

# Sender Emails

## List sender emails

> Lists all sender emails for the authenticated user's space with optional filtering by campaign ID and connection status. Supports pagination.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ListSenderEmailsResponse":{"type":"object","properties":{"hasMore":{"type":"boolean"},"limit":{"type":"integer"},"page":{"type":"integer"},"senderEmails":{"type":"array","items":{"$ref":"#/components/schemas/models.SenderEmailListItem"}},"total":{"type":"integer"}}},"models.SenderEmailListItem":{"type":"object","properties":{"address":{"type":"string"},"campaignIds":{"type":"array","items":{"type":"integer"}},"createdAt":{"type":"string"},"currentDailyLimit":{"type":"integer"},"familyName":{"type":"string"},"givenName":{"type":"string"},"id":{"type":"integer"},"isConnected":{"type":"boolean"},"manuallyDisconnected":{"type":"boolean"},"maximumSendingsLimitPerDay":{"type":"integer"},"minimumSendingsLimitPerDay":{"type":"integer"},"provider":{"type":"string"},"toggleGradualBuildUp":{"type":"boolean"},"updatedAt":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/sender-emails":{"get":{"description":"Lists all sender emails for the authenticated user's space with optional filtering by campaign ID and connection status. Supports pagination.","tags":["Sender Emails"],"summary":"List sender emails","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Page number (default: 1)","name":"page","in":"query"},{"schema":{"type":"integer"},"description":"Filter by space ID","name":"spaceId","in":"query"},{"schema":{"type":"integer"},"description":"Filter by campaign ID","name":"campaignId","in":"query"},{"schema":{"type":"boolean"},"description":"Filter by connection status","name":"isConnected","in":"query"}],"responses":{"200":{"description":"List of sender emails","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ListSenderEmailsResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"500":{"description":"Failed to retrieve sender emails","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Connect an SMTP/IMAP sender email

> Connects an SMTP/IMAP mailbox to the workspace using an app password, with no browser step. Google and Microsoft mailboxes are not supported here because both require an interactive consent screen; connect those in the app. The address must be a business domain.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ConnectSenderEmailResponse":{"type":"object","properties":{"message":{"type":"string"},"senderEmail":{"$ref":"#/components/schemas/models.SenderEmailResponse"}}},"models.SenderEmailResponse":{"type":"object","properties":{"address":{"type":"string"},"campaignIds":{"type":"array","items":{"type":"integer"}},"connectionHistory":{"type":"array","items":{"$ref":"#/components/schemas/models.ConnectionHistoryItem"}},"createdAt":{"type":"string"},"currentDailyLimit":{"type":"integer"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"familyName":{"type":"string"},"givenName":{"type":"string"},"id":{"type":"integer"},"isConnected":{"type":"boolean"},"lastDisconnectedAt":{"type":"string"},"lastReconnectedAt":{"type":"string"},"manuallyDisconnected":{"type":"boolean"},"maximumSendingsLimitPerDay":{"type":"integer"},"minimumSendingsLimitPerDay":{"type":"integer"},"pictureUrl":{"type":"string"},"provider":{"type":"string"},"provisioningStatus":{"type":"string"},"signature":{"type":"string"},"toggleGradualBuildUp":{"type":"boolean"},"updatedAt":{"type":"string"}}},"models.ConnectionHistoryItem":{"type":"object","properties":{"campaignId":{"type":"integer"},"createdAt":{"type":"string"},"disconnectionReason":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"eventType":{"type":"string"},"id":{"type":"integer"},"userId":{"type":"integer"}}},"models.ErrorInvalidSenderEmailAddress":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorSenderEmailPlanLimit":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorSenderEmailAlreadyConnected":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorFailedToConnectSenderEmail":{"type":"object","properties":{"error":{"type":"string"}}},"models.ConnectSenderEmailRequest":{"type":"object","required":["email","imapServerUrl","password","smtpServerUrl"],"properties":{"email":{"type":"string"},"firstName":{"type":"string","maxLength":255},"imapServerUrl":{"description":"ImapServerUrl and SmtpServerUrl accept the provider's host, optionally\nwith a port, for example \"imap.fastmail.com:993\".","type":"string","minLength":1},"lastName":{"type":"string","maxLength":255},"loginString":{"description":"LoginString defaults to the email address when omitted, which is what\nmost providers expect.","type":"string"},"password":{"type":"string","minLength":1},"smtpServerUrl":{"type":"string","minLength":1}}}}},"paths":{"/sender-emails":{"post":{"description":"Connects an SMTP/IMAP mailbox to the workspace using an app password, with no browser step. Google and Microsoft mailboxes are not supported here because both require an interactive consent screen; connect those in the app. The address must be a business domain.","tags":["Sender Emails"],"summary":"Connect an SMTP/IMAP sender email","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true}],"responses":{"201":{"description":"Sender email connected successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ConnectSenderEmailResponse"}}}},"400":{"description":"Invalid request body or non-business email address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidSenderEmailAddress"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"402":{"description":"Plan does not allow another sender email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorSenderEmailPlanLimit"}}}},"409":{"description":"Email already connected to another workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorSenderEmailAlreadyConnected"}}}},"500":{"description":"Failed to connect sender email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorFailedToConnectSenderEmail"}}}},"502":{"description":"Mail provider rejected the credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorFailedToConnectSenderEmail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ConnectSenderEmailRequest"}}},"description":"Mailbox credentials","required":true}}}}}
```

## Get a sender email by ID

> Retrieves detailed information about a specific sender email including connection status, limits, and settings.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.GetSenderEmailResponse":{"type":"object","properties":{"senderEmail":{"$ref":"#/components/schemas/models.SenderEmailResponse"}}},"models.SenderEmailResponse":{"type":"object","properties":{"address":{"type":"string"},"campaignIds":{"type":"array","items":{"type":"integer"}},"connectionHistory":{"type":"array","items":{"$ref":"#/components/schemas/models.ConnectionHistoryItem"}},"createdAt":{"type":"string"},"currentDailyLimit":{"type":"integer"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"familyName":{"type":"string"},"givenName":{"type":"string"},"id":{"type":"integer"},"isConnected":{"type":"boolean"},"lastDisconnectedAt":{"type":"string"},"lastReconnectedAt":{"type":"string"},"manuallyDisconnected":{"type":"boolean"},"maximumSendingsLimitPerDay":{"type":"integer"},"minimumSendingsLimitPerDay":{"type":"integer"},"pictureUrl":{"type":"string"},"provider":{"type":"string"},"provisioningStatus":{"type":"string"},"signature":{"type":"string"},"toggleGradualBuildUp":{"type":"boolean"},"updatedAt":{"type":"string"}}},"models.ConnectionHistoryItem":{"type":"object","properties":{"campaignId":{"type":"integer"},"createdAt":{"type":"string"},"disconnectionReason":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"eventType":{"type":"string"},"id":{"type":"integer"},"userId":{"type":"integer"}}},"models.ErrorInvalidSenderEmailID":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorForbidden":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorSenderEmailNotFound":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/sender-emails/{id}":{"get":{"description":"Retrieves detailed information about a specific sender email including connection status, limits, and settings.","tags":["Sender Emails"],"summary":"Get a sender email by ID","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Sender Email ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"Sender email details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.GetSenderEmailResponse"}}}},"400":{"description":"Invalid sender email ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidSenderEmailID"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Forbidden - sender email does not belong to your space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorForbidden"}}}},"404":{"description":"Sender email not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorSenderEmailNotFound"}}}}}}}}}
```

## Update a sender email by ID

> Updates an existing sender email's information. Only provided fields will be updated. Can update name, signature, and daily sending limits.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.UpdateSenderEmailResponse":{"type":"object","properties":{"message":{"type":"string"},"senderEmail":{"$ref":"#/components/schemas/models.SenderEmailResponse"}}},"models.SenderEmailResponse":{"type":"object","properties":{"address":{"type":"string"},"campaignIds":{"type":"array","items":{"type":"integer"}},"connectionHistory":{"type":"array","items":{"$ref":"#/components/schemas/models.ConnectionHistoryItem"}},"createdAt":{"type":"string"},"currentDailyLimit":{"type":"integer"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"familyName":{"type":"string"},"givenName":{"type":"string"},"id":{"type":"integer"},"isConnected":{"type":"boolean"},"lastDisconnectedAt":{"type":"string"},"lastReconnectedAt":{"type":"string"},"manuallyDisconnected":{"type":"boolean"},"maximumSendingsLimitPerDay":{"type":"integer"},"minimumSendingsLimitPerDay":{"type":"integer"},"pictureUrl":{"type":"string"},"provider":{"type":"string"},"provisioningStatus":{"type":"string"},"signature":{"type":"string"},"toggleGradualBuildUp":{"type":"boolean"},"updatedAt":{"type":"string"}}},"models.ConnectionHistoryItem":{"type":"object","properties":{"campaignId":{"type":"integer"},"createdAt":{"type":"string"},"disconnectionReason":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"eventType":{"type":"string"},"id":{"type":"integer"},"userId":{"type":"integer"}}},"models.ErrorInvalidSenderEmailID":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorForbidden":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorSenderEmailNotFound":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorFailedToUpdateSenderEmail":{"type":"object","properties":{"error":{"type":"string"}}},"models.UpdateSenderEmailRequest":{"type":"object","properties":{"currentDailyLimit":{"type":"integer","maximum":1000,"minimum":0},"familyName":{"type":"string","maxLength":255},"givenName":{"type":"string","maxLength":255,"minLength":1},"maximumSendingsLimitPerDay":{"description":"Daily sending limits","type":"integer","maximum":1000,"minimum":1},"minimumSendingsLimitPerDay":{"type":"integer","maximum":1000,"minimum":1},"signature":{"type":"string"},"toggleGradualBuildUp":{"description":"Gradual build-up toggle","type":"boolean"}}}}},"paths":{"/sender-emails/{id}":{"put":{"description":"Updates an existing sender email's information. Only provided fields will be updated. Can update name, signature, and daily sending limits.","tags":["Sender Emails"],"summary":"Update a sender email by ID","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Sender Email ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"Sender email updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateSenderEmailResponse"}}}},"400":{"description":"Invalid sender email ID or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidSenderEmailID"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Forbidden - sender email does not belong to your space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorForbidden"}}}},"404":{"description":"Sender email not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorSenderEmailNotFound"}}}},"500":{"description":"Failed to update sender email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorFailedToUpdateSenderEmail"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateSenderEmailRequest"}}},"description":"Sender email fields to update","required":true}}}}}
```