# Contacts

Manage contacts

## Create a new Contact

> Create a new contact

```json
{"openapi":"3.1.0","info":{"title":"Contacts","version":"2.0.0"},"tags":[{"name":"Contacts","description":"Manage contacts"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ContactCreateRequest_2":{"title":"ContactCreateRequest","type":"object","required":["contact"],"properties":{"contact":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"fields":{"type":"object"},"list_ids":{"type":"array","items":{"type":"integer"}}}}}},"Contact_2":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"fields":{"type":"object","description":"Object of fields in the following format:\n  field_1_merge_tag: string | integer | float | boolean | date string in ISO-8601 format (yyyy-mm-dd);"},"list_ids":{"type":"array","items":{"type":"integer"}},"status":{"type":"string","enum":["subscribed","unsubscribed"],"description":"The status of the contact:\n  - \"subscribed\" if its email was NOT in the suppression list\n  - \"unsubscribed\" otherwise"},"created_at":{"type":"integer","format":"timestampMillis"},"updated_at":{"type":"integer","format":"timestampMillis"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"title":"UnprocessableEntity","type":"object","properties":{"errors":{"type":"object","description":"Validation errors per attribute. Entire record errors are under `base` key."}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"LIMIT_EXCEEDED":{"description":"Rate limit exceeded for the current account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceededResponse"}}}},"INTERNAL_ERROR":{"description":"Internal error. Retry later or contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/accounts/{account_id}/contacts":{"post":{"operationId":"createContact","summary":"Create a new Contact","description":"Create a new contact","tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactCreateRequest_2"}}}},"responses":{"201":{"description":"Contact created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact_2"}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"409":{"description":"A Contact with the same email is already being created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Returns validation errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}},"429":{"$ref":"#/components/responses/LIMIT_EXCEEDED"},"500":{"$ref":"#/components/responses/INTERNAL_ERROR"}}}}}}
```

## Get contact

> Get contact using UUID or email (URL encoded)

```json
{"openapi":"3.1.0","info":{"title":"Contacts","version":"2.0.0"},"tags":[{"name":"Contacts","description":"Manage contacts"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Contact_2":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"fields":{"type":"object","description":"Object of fields in the following format:\n  field_1_merge_tag: string | integer | float | boolean | date string in ISO-8601 format (yyyy-mm-dd);"},"list_ids":{"type":"array","items":{"type":"integer"}},"status":{"type":"string","enum":["subscribed","unsubscribed"],"description":"The status of the contact:\n  - \"subscribed\" if its email was NOT in the suppression list\n  - \"unsubscribed\" otherwise"},"created_at":{"type":"integer","format":"timestampMillis"},"updated_at":{"type":"integer","format":"timestampMillis"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NOT_FOUND":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"LIMIT_EXCEEDED":{"description":"Rate limit exceeded for the current account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceededResponse"}}}},"INTERNAL_ERROR":{"description":"Internal error. Retry later or contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/accounts/{account_id}/contacts/{contact_identifier}":{"get":{"description":"Get contact using UUID or email (URL encoded)","operationId":"getContact","summary":"Get contact","tags":["Contacts"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact_2"}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"404":{"$ref":"#/components/responses/NOT_FOUND"},"429":{"$ref":"#/components/responses/LIMIT_EXCEEDED"},"500":{"$ref":"#/components/responses/INTERNAL_ERROR"}}}}}}
```

## Delete contact

> Delete contact using UUID or email (URL encoded)

```json
{"openapi":"3.1.0","info":{"title":"Contacts","version":"2.0.0"},"tags":[{"name":"Contacts","description":"Manage contacts"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NOT_FOUND":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"LIMIT_EXCEEDED":{"description":"Rate limit exceeded for the current account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceededResponse"}}}},"INTERNAL_ERROR":{"description":"Internal error. Retry later or contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}}},"paths":{"/api/accounts/{account_id}/contacts/{contact_identifier}":{"delete":{"description":"Delete contact using UUID or email (URL encoded)","operationId":"deleteContact","summary":"Delete contact","tags":["Contacts"],"responses":{"204":{"description":"Contact successfully deleted"},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"404":{"$ref":"#/components/responses/NOT_FOUND"},"429":{"$ref":"#/components/responses/LIMIT_EXCEEDED"},"500":{"$ref":"#/components/responses/INTERNAL_ERROR"}}}}}}
```

## Update contact

> Update contact using UUID or email (URL encoded)

```json
{"openapi":"3.1.0","info":{"title":"Contacts","version":"2.0.0"},"tags":[{"name":"Contacts","description":"Manage contacts"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ContactUpdateRequest_2":{"title":"ContactUpdateRequest","type":"object","required":["contact"],"properties":{"contact":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"fields":{"type":"object"},"list_ids_included":{"type":"array","items":{"type":"integer"}},"list_ids_excluded":{"type":"array","items":{"type":"integer"}},"unsubscribed":{"type":"boolean"}}}}},"ContactUpdateResponse_2":{"title":"ContactUpdateResponse","type":"object","properties":{"action":{"type":"string","enum":["created","updated"],"description":"Performed action on the contact:\n  - \"created\" if contact does not exist\n  - \"updated\" if contact exists"},"data":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"fields":{"type":"object","description":"Object of fields in the following format:\n  field_1_merge_tag: string | integer | float | boolean | date string in ISO-8601 format (yyyy-mm-dd);"},"list_ids":{"type":"array","items":{"type":"integer"}},"status":{"type":"string","enum":["subscribed","unsubscribed"],"description":"The status of the contact:\n  - \"subscribed\" if its email was NOT in the suppression list\n  - \"unsubscribed\" otherwise"},"created_at":{"type":"integer","format":"timestampMillis"},"updated_at":{"type":"integer","format":"timestampMillis"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"title":"UnprocessableEntity","type":"object","properties":{"errors":{"type":"object","description":"Validation errors per attribute. Entire record errors are under `base` key."}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"LIMIT_EXCEEDED":{"description":"Rate limit exceeded for the current account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceededResponse"}}}},"INTERNAL_ERROR":{"description":"Internal error. Retry later or contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/accounts/{account_id}/contacts/{contact_identifier}":{"patch":{"description":"Update contact using UUID or email (URL encoded)","operationId":"updateContact","summary":"Update contact","tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdateRequest_2"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdateResponse_2"}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"409":{"description":"A Contact with the same email is already being created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Returns validation errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}},"429":{"$ref":"#/components/responses/LIMIT_EXCEEDED"},"500":{"$ref":"#/components/responses/INTERNAL_ERROR"}}}}}}
```
