> ## Documentation Index > Fetch the complete documentation index at: https://docs.indiepitcher.com/llms.txt > Use this file to discover all available pages before exploring further. # Add a new contact > Add a new contact to the mailing list, or update an existing one if `updateIfExists` is set to `true`. ## OpenAPI ````yaml post /contacts/create openapi: 3.0.3 info: title: IndiePitcher OpenAPI Spec description: >- ## Welcome IndiePitcher REST API allows you to send emails, manage your contacts, and generate portal session to manage user's contact lists. Please note that most destructive operations are currently not supported through the REST API for sesucurity reasons. Please use the [IndiePitcher dashboard](https://app.indiepitcher.com). ## Base URL All requests contain the following base URL: ``` https://api.indiepitcher.com/v1 ``` ## Authentication - Create a free account at [IndiePitcher](https://app.indiepitcher.com) to get your API key. API keys are tied to a project. - After you've generated your API key you can use it to authenticate your requests by including it in the `Authorization` header. ```http Authorization: Bearer sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ## SDKs SDKs are available for the following languages: - [Node.js](https://github.com/IndiePitcher/indiepitcher-node) - [Swift](https://github.com/IndiePitcher/indiepitcher-swift) (server-side usage only) ## Rate Limits Rate limits are applied to all requests to the IndiePitcher API. The rate limits are as follows: - **10 requests per second across API keys tied to a project.** After reaching the rate limit, you will receive a `429 Too Many Requests` response. The rate limit will reset after 1 second. We recommend using endpoints that support batch operations to reduce the number of requests made. ## Quick Start Guide ### Send a simple email ```bash curl --request POST \ --url https://api.indiepitcher.com/v1/email/transactional \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "to": "john@acme.com", "subject": "You have been invited to IndiePitcher", "body": "This is a sample body that supports **markdown**. Plain html is also supported.", "bodyFormat": "markdown" }' ``` version: 1.2.0 termsOfService: http://indiepitcher.com/terms contact: email: petr@indiepitcher.com servers: - url: https://api.indiepitcher.com/v1 security: [] tags: - name: Email - name: Contacts - name: Mailing Lists externalDocs: description: Find out more about IndiePitcher url: http://docs.indiepitcher.com paths: /contacts/create: post: tags: - Contacts summary: Add a new contact description: >- Add a new contact to the mailing list, or update an existing one if `updateIfExists` is set to `true`. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateContact' required: true responses: '200': description: A created or updated contact content: application/json: schema: type: object properties: success: type: boolean data: $ref: '#/components/schemas/Contact' security: - apiKey: [] components: schemas: CreateContact: type: object properties: email: type: string description: The email of the contact. example: john@acme.com userId: type: string nullable: true description: The user id of the contact. example: '1234567' avatarUrl: type: string nullable: true description: The avatar url of the contact. example: https://example.com/avatar.jpg name: type: string nullable: true description: The full name of the contact. example: John Doe languageCode: type: string nullable: true description: The language code of the contact. example: en_US updateIfExists: type: boolean nullable: true description: >- If a contact with the provided email already exists, update the contact with the new data. ignoreListSubscriptionsWhenUpdating: type: boolean nullable: true description: >- Whether to ignore `subscribedToLists` field if the contact already exists and `updateIfExists` is set to `true`. Useful to avoid accidentally resubscribing a contact to lists they unsubscribed before. Default value is `true`. subscribedToLists: type: array items: type: string description: The array of mailing lists the contact is subscribed to. example: - onboarding - newsletter customProperties: type: object additionalProperties: $ref: '#/components/schemas/CustomContactPropertyValue' description: The custom properties set for this contact. example: company: Acme age: 35 required: - email Contact: required: - email type: object properties: email: type: string description: The email of the contact. example: john@acme.com userId: type: string description: The user id of the contact. example: 123456 name: type: string description: The full name of the contact example: John Doe avatarUrl: type: string description: The avatar url of the contact example: https://example.com/profile_pictures/123456 languageCode: type: string description: >- The primary language language of this contact, represented by a language code. example: en-US hardBouncedAt: type: string description: >- The date when an attempt to send an email to the contact failed with a hard bounce, meaning the email address is invalid and no further emails will be send to this contact. You can reset this in the dashboard to re-enable sending emails to this contact. example: '2024-04-23T18:25:43.511Z' subscribedToLists: type: array items: type: string description: The array of mailing lists the contact is subscribed to. example: - onboarding - newsletter customProperties: type: object additionalProperties: $ref: '#/components/schemas/CustomContactPropertyValue' description: The custom properties set for this contact. example: company: Acme age: 35 CustomContactPropertyValue: type: object description: >- Represents a custom contact property, which can be a string, number, boolean, or date. oneOf: - type: string description: A string property. - type: number format: double description: A number property. - type: boolean description: A boolean property. - type: string format: date-time description: A date property. securitySchemes: apiKey: type: http scheme: bearer ````